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 many of the tools, including
162 GHC itself. If you need to port GHC to your platform
163 because there isn't a binary distribution of GHC available,
164 then see <xref linkend="sec-porting-ghc"/>.</para>
166 <para>Which version of GHC you need will depend on the
167 packages you intend to build. GHC itself will normally
168 build using one of several older versions of itself - check
169 the announcement or release notes for details.</para>
175 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
176 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
179 <para><emphasis>You have to have Perl to proceed!</emphasis>
180 Perl version 5 at least is required. GHC has been known to
181 tickle bugs in Perl, so if you find that Perl crashes when
182 running GHC try updating (or downgrading) your Perl
183 installation. Versions of Perl before 5.6 have been known to have
184 various bugs tickled by GHC, so the configure script
185 will look for version 5.6 or later.</para>
187 <para>For Win32 platforms, you should use the binary
188 supplied in the InstallShield (copy it to
189 <filename>/bin</filename>). The Cygwin-supplied Perl seems
192 <para>Perl should be put somewhere so that it can be invoked
193 by the <literal>#!</literal> script-invoking
194 mechanism. The full pathname may need to be less than 32
195 characters long on some systems.</para>
200 <term>GNU C (<command>gcc</command>)
201 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
202 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
205 <para>Most GCC versions should work with the most recent GHC
206 sources. Expect trouble if you use a recent GCC with
207 an older GHC, though (trouble in the form of mis-compiled code,
208 link errors, and errors from the <literal>ghc-asm</literal>
211 <para>If your GCC dies with “internal error” on
212 some GHC source file, please let us know, so we can report
213 it and get things improved. (Exception: on x86
214 boxes—you may need to fiddle with GHC's
215 <option>-monly-N-regs</option> option; see the User's
222 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
225 <para>The fptools build system makes heavy use of features
226 specific to GNU <command>make</command>, so you must have
227 this installed in order to build any of the fptools
230 <para>NB. it has been reported that version 3.79 no longer
231 works to build GHC, and 3.80 is required.</para>
236 <term><ulink url="http://www.haskell.org/happy">Happy</ulink>
237 <indexterm><primary>Happy</primary></indexterm>
240 <para>Happy is a parser generator tool for Haskell, and is
241 used to generate GHC's parsers.</para>
243 <para>If you start from a source tarball of GHC (i.e. not a darcs
244 checkout), then you don't need Happy, because we supply the
245 pre-processed versions of the Happy parsers. If you intend to
246 modify the compiler and/or you're using a darcs checkout, then you
249 <para>Happy version 1.15 is currently required to build GHC.</para>
251 <para>Happy is written in
252 Haskell, and is a project in the CVS repository
253 (<literal>fptools/happy</literal>). It can be built from
254 source, but bear in mind that you'll need GHC installed in
255 order to build it. To avoid the chicken/egg problem,
256 install a binary distribution of either Happy or GHC to get
257 started. Happy distributions are available from <ulink url="http://www.haskell.org/happy/">Happy's Web
264 <indexterm><primary>Alex</primary></indexterm>
267 <para>Alex is a lexical-analyser generator for Haskell,
268 which GHC uses to generate its lexer.</para>
270 <para>Like Happy, you don't need Alex if you're building GHC from a
271 source tarball, but you do need it if you're modifying GHC and/or
272 building a darcs checkout.</para>
275 written in Haskell and is a project in the darcs repository.
276 Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
283 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
284 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
287 <para>GNU autoconf is needed if you intend to build from the
288 darcs sources, it is <emphasis>not</emphasis> needed if you
289 just intend to build a standard source distribution.</para>
291 <para>Version 2.52 or later of the autoconf package is required.
292 NB. version 2.13 will no longer work, as of GHC version
295 <para><command>autoreconf</command> (from the autoconf package)
296 recursively builds <command>configure</command> scripts from
297 the corresponding <filename>configure.ac</filename> and
298 <filename>aclocal.m4</filename> files. If you modify one of
299 the latter files, you'll need <command>autoreconf</command> to
300 rebuild the corresponding <filename>configure</filename>.</para>
305 <term><command>sed</command>
306 <indexterm><primary>pre-supposed: sed</primary></indexterm>
307 <indexterm><primary>sed, pre-supposed</primary></indexterm>
310 <para>You need a working <command>sed</command> if you are
311 going to build from sources. The build-configuration stuff
312 needs it. GNU sed version 2.0.4 is no good! It has a bug
313 in it that is tickled by the build-configuration. 2.0.5 is
314 OK. Others are probably OK too (assuming we don't create too
315 elaborate configure scripts.)</para>
320 <para>One <literal>fptools</literal> project is worth a quick note
321 at this point, because it is useful for all the others:
322 <literal>glafp-utils</literal> contains several utilities which
323 aren't particularly Glasgow-ish, but Occasionally Indispensable.
324 Like <command>lndir</command> for creating symbolic link
327 <sect2 id="pre-supposed-gph-tools">
328 <title>Tools for building parallel GHC (GPH)</title>
333 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
334 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
337 <para>PVM is the Parallel Virtual Machine on which
338 Parallel Haskell programs run. (You only need this if you
339 plan to run Parallel Haskell. Concurrent Haskell, which
340 runs concurrent threads on a uniprocessor doesn't need
341 it.) Underneath PVM, you can have (for example) a network
342 of workstations (slow) or a multiprocessor box
345 <para>The current version of PVM is 3.3.11; we use 3.3.7.
346 It is readily available on the net; I think I got it from
347 <literal>research.att.com</literal>, in
348 <filename>netlib</filename>.</para>
350 <para>A PVM installation is slightly quirky, but easy to
351 do. Just follow the <filename>Readme</filename>
357 <term><command>bash</command>:
358 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
361 <para>Sadly, the <command>gr2ps</command> script, used to
362 convert “parallelism profiles” to PostScript,
363 is written in Bash (GNU's Bourne Again shell). This bug
364 will be fixed (someday).</para>
370 <sect2 id="pre-supposed-other-tools">
371 <title>Other useful tools</title>
376 <indexterm><primary>pre-supposed: flex</primary></indexterm>
377 <indexterm><primary>flex, pre-supposed</primary></indexterm>
380 <para>This is a quite-a-bit-better-than-Lex lexer. Used
381 to build a couple of utilities in
382 <literal>glafp-utils</literal>. Depending on your
383 operating system, the supplied <command>lex</command> may
384 or may not work; you should get the GNU version.</para>
389 <para>More tools are required if you want to format the documentation
390 that comes with GHC and other fptools projects. See <xref
391 linkend="building-docs"/>.</para>
395 <sect1 id="sec-building-from-source">
396 <title>Building from source</title>
398 <indexterm><primary>Building from source</primary></indexterm>
399 <indexterm><primary>Source, building from</primary></indexterm>
401 <para>“I just want to build it!”</para>
403 <para>No problem. This recipe should build and install a working GHC with
404 all the default settings. (unless you're
405 on Windows, in which case go to <xref linkend="winbuild" />).</para>
407 <screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
411 $ make install</screen>
413 <para>For GHC, this will do a 2-stage bootstrap build of the
414 compiler, with profiling libraries, and install the
415 results in the default location (under <filename>/usr/local</filename> on
416 Unix, for example).</para>
418 <para>The <literal>configure</literal> script is a standard GNU
419 <literal>autoconf</literal> script, and accepts the usual options for
420 changing install locations and the like. Run
421 <literal>./configure --help</literal> for a list of options.</para>
423 <para>If you want to do anything at all non-standard, or you
424 want to do some development, read on...</para>
427 <sect1 id="quick-start">
428 <title>Quick start for GHC developers</title>
430 <para>This section is a copy of the file
431 <literal>ghc/HACKING</literal> from the GHC source tree. It describes
432 how to get started with setting up your build tree for developing GHC
433 or its libraries, and how to start building.</para>
440 <sect1 id="sec-working-with-the-build-system">
441 <title>Working with the build system</title>
443 <para>This rest of this guide is intended for duffers like me, who
444 aren't really interested in Makefiles and systems configurations,
445 but who need a mental model of the interlocking pieces so that
446 they can make them work, extend them consistently when adding new
447 software, and lay hands on them gently when they don't
450 <sect2 id="sec-source-tree">
451 <title>Your source tree</title>
453 <para>The source code is held in your <emphasis>source
454 tree</emphasis>. The root directory of your source tree
455 <emphasis>must</emphasis> contain the following directories and
460 <para><filename>Makefile</filename>: the root
465 <para><filename>mk/</filename>: the directory that contains
466 the main Makefile code, shared by all the
467 <literal>fptools</literal> software.</para>
471 <para><filename>configure.ac</filename>,
472 <filename>config.sub</filename>,
473 <filename>config.guess</filename>: these files support the
474 configuration process.</para>
478 <para><filename>install-sh</filename>.</para>
482 <para>All the other directories are individual
483 <emphasis>projects</emphasis> of the <literal>fptools</literal>
484 system—for example, the Glasgow Haskell Compiler
485 (<literal>ghc</literal>), the Happy parser generator
486 (<literal>happy</literal>), the <literal>nofib</literal>
487 benchmark suite, and so on. You can have zero or more of these.
488 Needless to say, some of them are needed to build others.</para>
490 <para>The important thing to remember is that even if you want
491 only one project (<literal>happy</literal>, say), you must have
492 a source tree whose root directory contains
493 <filename>Makefile</filename>, <filename>mk/</filename>,
494 <filename>configure.ac</filename>, and the project(s) you want
495 (<filename>happy/</filename> in this case). You cannot get by
496 with just the <filename>happy/</filename> directory.</para>
500 <title>Build trees</title>
501 <indexterm><primary>build trees</primary></indexterm>
502 <indexterm><primary>link trees, for building</primary></indexterm>
504 <para>If you just want to build the software once on a single
505 platform, then your source tree can also be your build tree, and
506 you can skip the rest of this section.</para>
508 <para>We often want to build multiple versions of our software
509 for different architectures, or with different options
510 (e.g. profiling). It's very desirable to share a single copy of
511 the source code among all these builds.</para>
513 <para>So for every source tree we have zero or more
514 <emphasis>build trees</emphasis>. Each build tree is initially
515 an exact copy of the source tree, except that each file is a
516 symbolic link to the source file, rather than being a copy of
517 the source file. There are “standard” Unix
518 utilities that make such copies, so standard that they go by
520 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
521 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
522 are two (If you don't have either, the source distribution
523 includes sources for the X11
524 <command>lndir</command>—check out
525 <filename>fptools/glafp-utils/lndir</filename>). See <xref
526 linkend="sec-storysofar"/> for a typical invocation.</para>
528 <para>The build tree does not need to be anywhere near the
529 source tree in the file system. Indeed, one advantage of
530 separating the build tree from the source is that the build tree
531 can be placed in a non-backed-up partition, saving your systems
532 support people from backing up untold megabytes of
533 easily-regenerated, and rapidly-changing, gubbins. The golden
534 rule is that (with a single exception—<xref
535 linkend="sec-build-config"/>) <emphasis>absolutely everything in
536 the build tree is either a symbolic link to the source tree, or
537 else is mechanically generated</emphasis>. It should be
538 perfectly OK for your build tree to vanish overnight; an hour or
539 two compiling and you're on the road again.</para>
541 <para>You need to be a bit careful, though, that any new files
542 you create (if you do any development work) are in the source
543 tree, not a build tree!</para>
545 <para>Remember, that the source files in the build tree are
546 <emphasis>symbolic links</emphasis> to the files in the source
547 tree. (The build tree soon accumulates lots of built files like
548 <filename>Foo.o</filename>, as well.) You can
549 <emphasis>delete</emphasis> a source file from the build tree
550 without affecting the source tree (though it's an odd thing to
551 do). On the other hand, if you <emphasis>edit</emphasis> a
552 source file from the build tree, you'll edit the source-tree
553 file directly. (You can set up Emacs so that if you edit a
554 source file from the build tree, Emacs will silently create an
555 edited copy of the source file in the build tree, leaving the
556 source file unchanged; but the danger is that you think you've
557 edited the source file whereas actually all you've done is edit
558 the build-tree copy. More commonly you do want to edit the
561 <para>Like the source tree, the top level of your build tree
562 must be (a linked copy of) the root directory of the
563 <literal>fptools</literal> suite. Inside Makefiles, the root of
564 your build tree is called
565 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
566 In the rest of this document path names are relative to
567 <constant>$(FPTOOLS_TOP)</constant> unless
568 otherwise stated. For example, the file
569 <filename>ghc/mk/target.mk</filename> is actually
570 <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
573 <sect2 id="sec-build-config">
574 <title>Getting the build you want</title>
576 <para>When you build <literal>fptools</literal> you will be
577 compiling code on a particular <emphasis>host
578 platform</emphasis>, to run on a particular <emphasis>target
579 platform</emphasis> (usually the same as the host
580 platform)<indexterm><primary>platform</primary></indexterm>.
581 The difficulty is that there are minor differences between
582 different platforms; minor, but enough that the code needs to be
583 a bit different for each. There are some big differences too:
584 for a different architecture we need to build GHC with a
585 different native-code generator.</para>
587 <para>There are also knobs you can turn to control how the
588 <literal>fptools</literal> software is built. For example, you
589 might want to build GHC optimised (so that it runs fast) or
590 unoptimised (so that you can compile it fast after you've
591 modified it. Or, you might want to compile it with debugging on
592 (so that extra consistency-checking code gets included) or off.
595 <para>All of this stuff is called the
596 <emphasis>configuration</emphasis> of your build. You set the
597 configuration using a three-step process.</para>
601 <term>Step 1: get ready for configuration.</term>
603 <para>NOTE: if you're starting from a source distribution,
604 rather than darcs sources, you can skip this step.</para>
606 <para>Change directory to
607 <constant>$(FPTOOLS_TOP)</constant> and
608 issue the command</para>
609 <screen>$ autoreconf</screen>
610 <indexterm><primary>autoreconf</primary></indexterm>
611 <para>(with no arguments). This GNU program (recursively) converts
612 <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
613 <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
614 to a shell script called
615 <filename>$(FPTOOLS_TOP)/configure</filename>.
616 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
617 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
618 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
619 a message like "No rule to make target 'mk/config.h.in'".
622 <para>Some projects, including GHC, have their own configure script.
623 <command>autoreconf</command> takes care of that, too, so all you have
624 to do is calling <command>autoreconf</command> in the top-level directory
625 <filename>$(FPTOOLS_TOP)</filename>.</para>
627 <para>These steps are completely platform-independent; they just mean
628 that the human-written files (<filename>configure.ac</filename> and
629 <filename>aclocal.m4</filename>) can be short, although the resulting
630 files (the <command>configure</command> shell scripts and the C header
631 template <filename>mk/config.h.in</filename>) are long.</para>
636 <term>Step 2: system configuration.</term>
638 <para>Runs the newly-created <command>configure</command>
641 <screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
643 <para><command>configure</command>'s mission is to scurry
644 round your computer working out what architecture it has,
645 what operating system, whether it has the
646 <function>vfork</function> system call, where
647 <command>tar</command> is kept, whether
648 <command>gcc</command> is available, where various obscure
649 <literal>#include</literal> files are, whether it's a
650 leap year, and what the systems manager had for lunch. It
651 communicates these snippets of information in two
658 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
660 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
661 substituting for things between
662 “<literal>@</literal>” brackets. So,
663 “<literal>@HaveGcc@</literal>” will be
664 replaced by “<literal>YES</literal>” or
665 “<literal>NO</literal>” depending on what
666 <command>configure</command> finds.
667 <filename>mk/config.mk</filename> is included by every
668 Makefile (directly or indirectly), so the
669 configuration information is thereby communicated to
670 all Makefiles.</para>
675 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
677 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
678 The latter is <literal>#include</literal>d by
679 various C programs, which can thereby make use of
680 configuration information.</para>
684 <para><command>configure</command> takes some optional
685 arguments. Use <literal>./configure --help</literal> to
686 get a list of the available arguments. Here are some of
687 the ones you might need:</para>
691 <term><literal>--with-ghc=<parameter>path</parameter></literal>
692 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
695 <para>Specifies the path to an installed GHC which
696 you would like to use. This compiler will be used
697 for compiling GHC-specific code (eg. GHC itself).
698 This option <emphasis>cannot</emphasis> be specified
699 using <filename>build.mk</filename> (see later),
700 because <command>configure</command> needs to
701 auto-detect the version of GHC you're using. The
702 default is to look for a compiler named
703 <literal>ghc</literal> in your path.</para>
708 <term><literal>--with-hc=<parameter>path</parameter></literal>
709 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
712 <para>Specifies the path to any installed Haskell
713 compiler. This compiler will be used for compiling
714 generic Haskell code. The default is to use
715 <literal>ghc</literal>.</para>
720 <term><literal>--with-gcc=<parameter>path</parameter></literal>
721 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
724 <para>Specifies the path to the installed GCC. This
725 compiler will be used to compile all C files,
726 <emphasis>except</emphasis> any generated by the
727 installed Haskell compiler, which will have its own
728 idea of which C compiler (if any) to use. The
729 default is to use <literal>gcc</literal>.</para>
737 <term>Step 3: build configuration.</term>
739 <para>Next, you say how this build of
740 <literal>fptools</literal> is to differ from the standard
741 defaults by creating a new file
742 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
743 <emphasis>in the build tree</emphasis>. This file is the
744 one and only file you edit in the build tree, precisely
745 because it says how this build differs from the source.
746 (Just in case your build tree does die, you might want to
747 keep a private directory of <filename>build.mk</filename>
748 files, and use a symbolic link in each build tree to point
749 to the appropriate one.) So
750 <filename>mk/build.mk</filename> never exists in the
751 source tree—you create one in each build tree from
752 the template. We'll discuss what to put in it
758 <para>And that's it for configuration. Simple, eh?</para>
760 <para>What do you put in your build-specific configuration file
761 <filename>mk/build.mk</filename>? <emphasis>For almost all
762 purposes all you will do is put make variable definitions that
763 override those in</emphasis>
764 <filename>mk/config.mk.in</filename>. The whole point of
765 <filename>mk/config.mk.in</filename>—and its derived
766 counterpart <filename>mk/config.mk</filename>—is to define
767 the build configuration. It is heavily commented, as you will
768 see if you look at it. So generally, what you do is look at
769 <filename>mk/config.mk.in</filename>, and add definitions in
770 <filename>mk/build.mk</filename> that override any of the
771 <filename>config.mk</filename> definitions that you want to
772 change. (The override occurs because the main boilerplate file,
773 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
774 includes <filename>build.mk</filename> after
775 <filename>config.mk</filename>.)</para>
777 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
778 that can serve as a starting point for your <filename>build.mk</filename>.</para>
780 <para>For example, <filename>config.mk.in</filename> contains
781 the definition:</para>
783 <programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
785 <para>The accompanying comment explains that this is the list of
786 flags passed to GHC when building GHC itself. For doing
787 development, it is wise to add <literal>-DDEBUG</literal>, to
788 enable debugging code. So you would add the following to
789 <filename>build.mk</filename>:</para>
791 <para>or, if you prefer,</para>
793 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
795 <para>GNU <command>make</command> allows existing definitions to
796 have new text appended using the “<literal>+=</literal>”
797 operator, which is quite a convenient feature.)</para>
799 <para>If you want to remove the <literal>-O</literal> as well (a
800 good idea when developing, because the turn-around cycle gets a
801 lot quicker), you can just override
802 <literal>GhcLibHcOpts</literal> altogether:</para>
804 <programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
806 <para>When reading <filename>config.mk.in</filename>, remember
807 that anything between “@...@” signs is going to be substituted
808 by <command>configure</command> later. You
809 <emphasis>can</emphasis> override the resulting definition if
810 you want, but you need to be a bit surer what you are doing.
811 For example, there's a line that says:</para>
813 <programlisting>TAR = @TarCmd@</programlisting>
815 <para>This defines the Make variables <constant>TAR</constant>
816 to the pathname for a <command>tar</command> that
817 <command>configure</command> finds somewhere. If you have your
818 own pet <command>tar</command> you want to use instead, that's
819 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
821 <programlisting>TAR = mytar</programlisting>
823 <para>You do not <emphasis>have</emphasis> to have a
824 <filename>mk/build.mk</filename> file at all; if you don't,
825 you'll get all the default settings from
826 <filename>mk/config.mk.in</filename>.</para>
828 <para>You can also use <filename>build.mk</filename> to override
829 anything that <command>configure</command> got wrong. One place
830 where this happens often is with the definition of
831 <constant>FPTOOLS_TOP_ABS</constant>: this
832 variable is supposed to be the canonical path to the top of your
833 source tree, but if your system uses an automounter then the
834 correct directory is hard to find automatically. If you find
835 that <command>configure</command> has got it wrong, just put the
836 correct definition in <filename>build.mk</filename>.</para>
840 <sect2 id="sec-storysofar">
841 <title>The story so far</title>
843 <para>Let's summarise the steps you need to carry to get
844 yourself a fully-configured build tree from scratch.</para>
848 <para> Get your source tree from somewhere (darcs repository
849 or source distribution). Say you call the root directory
850 <filename>myfptools</filename> (it does not have to be
851 called <filename>fptools</filename>). Make sure that you
852 have the essential files (see <xref
853 linkend="sec-source-tree"/>).</para>
858 <para>(Optional) Use <command>lndir</command> or
859 <command>mkshadowdir</command> to create a build tree.</para>
861 <screen>$ cd myfptools
862 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
864 <para>(N.B. <command>mkshadowdir</command>'s first argument
865 is taken relative to its second.) You probably want to give
866 the build tree a name that suggests its main defining
867 characteristic (in your mind at least), in case you later
872 <para>Change directory to the build tree. Everything is
873 going to happen there now.</para>
875 <screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
880 <para>Prepare for system configuration:</para>
882 <screen>$ autoreconf</screen>
884 <para>(You can skip this step if you are starting from a
885 source distribution, and you already have
886 <filename>configure</filename> and
887 <filename>mk/config.h.in</filename>.)</para>
891 <para>Do system configuration:</para>
893 <screen>$ ./configure</screen>
895 <para>Don't forget to check whether you need to add any
896 arguments to <literal>configure</literal>; for example, a
897 common requirement is to specify which GHC to use with
898 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
902 <para>Create the file <filename>mk/build.mk</filename>,
903 adding definitions for your desired configuration
906 <screen>$ emacs mk/build.mk</screen>
910 <para>You can make subsequent changes to
911 <filename>mk/build.mk</filename> as often as you like. You do
912 not have to run any further configuration programs to make these
913 changes take effect. In theory you should, however, say
914 <command>gmake clean</command>, <command>gmake all</command>,
915 because configuration option changes could affect
916 anything—but in practice you are likely to know what's
921 <title>Making things</title>
923 <para>At this point you have made yourself a fully-configured
924 build tree, so you are ready to start building real
927 <para>The first thing you need to know is that <emphasis>you
928 must use GNU <command>make</command>, usually called
929 <command>gmake</command>, not standard Unix
930 <command>make</command></emphasis>. If you use standard Unix
931 <command>make</command> you will get all sorts of error messages
932 (but no damage) because the <literal>fptools</literal>
933 <command>Makefiles</command> use GNU <command>make</command>'s
934 facilities extensively.</para>
936 <para>To just build the whole thing, <command>cd</command> to
937 the top of your <literal>fptools</literal> tree and type
938 <command>gmake</command>. This will prepare the tree and build
939 the various projects in the correct order.</para>
942 <sect2 id="sec-bootstrapping">
943 <title>Bootstrapping GHC</title>
945 <para>GHC requires a 2-stage bootstrap in order to provide
946 full functionality, including GHCi. By a 2-stage bootstrap, we
947 mean that the compiler is built once using the installed GHC,
948 and then again using the compiler built in the first stage. You
949 can also build a stage 3 compiler, but this normally isn't
950 necessary except to verify that the stage 2 compiler is working
953 <para>Note that when doing a bootstrap, the stage 1 compiler
954 must be built, followed by the runtime system and libraries, and
955 then the stage 2 compiler. The correct ordering is implemented
956 by the top-level fptools <filename>Makefile</filename>, so if
957 you want everything to work automatically it's best to start
958 <command>make</command> from the top of the tree. When building
959 GHC, the top-level fptools <filename>Makefile</filename> is set
960 up to do a 2-stage bootstrap by default (when you say
961 <command>make</command>). Some other targets it supports
968 <para>Build everything as normal, including the stage 1
976 <para>Build the stage 2 compiler only.</para>
983 <para>Build the stage 3 compiler only.</para>
988 <term>bootstrap</term> <term>bootstrap2</term>
990 <para>Build stage 1 followed by stage 2.</para>
995 <term>bootstrap3</term>
997 <para>Build stages 1, 2 and 3.</para>
1002 <term>install</term>
1004 <para>Install everything, including the compiler built in
1005 stage 2. To override the stage, say <literal>make install
1006 stage=<replaceable>n</replaceable></literal> where
1007 <replaceable>n</replaceable> is the stage to install.</para>
1012 <para>The top-level <filename>Makefile</filename> also arranges
1013 to do the appropriate <literal>make boot</literal> steps (see
1014 below) before actually building anything.</para>
1016 <para>The <literal>stage1</literal>, <literal>stage2</literal>
1017 and <literal>stage3</literal> targets also work in the
1018 <literal>ghc/compiler</literal> directory, but don't forget that
1019 each stage requires its own <literal>make boot</literal> step:
1020 for example, you must do</para>
1022 <screen>$ make boot stage=2</screen>
1024 <para>before <literal>make stage2</literal> in
1025 <literal>ghc/compiler</literal>.</para>
1028 <sect2 id="sec-standard-targets">
1029 <title>Standard Targets</title>
1030 <indexterm><primary>targets, standard makefile</primary></indexterm>
1031 <indexterm><primary>makefile targets</primary></indexterm>
1033 <para>In any directory you should be able to make the following:</para>
1037 <term><literal>boot</literal></term>
1039 <para>does the one-off preparation required to get ready
1040 for the real work. Notably, it does <command>gmake
1041 depend</command> in all directories that contain programs.
1042 It also builds the necessary tools for compilation to
1045 <para>Invoking the <literal>boot</literal> target
1046 explicitly is not normally necessary. From the top-level
1047 <literal>fptools</literal> directory, invoking
1048 <literal>gmake</literal> causes <literal>gmake boot
1049 all</literal> to be invoked in each of the project
1050 subdirectories, in the order specified by
1051 <literal>$(AllTargets)</literal> in
1052 <literal>config.mk</literal>.</para>
1054 <para>If you're working in a subdirectory somewhere and
1055 need to update the dependencies, <literal>gmake
1056 boot</literal> is a good way to do it.</para>
1061 <term><literal>all</literal></term>
1063 <para>makes all the final target(s) for this Makefile.
1064 Depending on which directory you are in a “final
1065 target” may be an executable program, a library
1066 archive, a shell script, or a Postscript file. Typing
1067 <command>gmake</command> alone is generally the same as
1068 typing <command>gmake all</command>.</para>
1073 <term><literal>install</literal></term>
1075 <para>installs the things built by <literal>all</literal>
1076 (except for the documentation). Where does it install
1077 them? That is specified by
1078 <filename>mk/config.mk.in</filename>; you can override it
1079 in <filename>mk/build.mk</filename>, or by running
1080 <command>configure</command> with command-line arguments
1081 like <literal>--bindir=/home/simonpj/bin</literal>; see
1082 <literal>./configure --help</literal> for the full
1088 <term><literal>install-docs</literal></term>
1090 <para>installs the documentation. Otherwise behaves just
1091 like <literal>install</literal>.</para>
1096 <term><literal>uninstall</literal></term>
1098 <para>reverses the effect of
1099 <literal>install</literal>.</para>
1104 <term><literal>clean</literal></term>
1106 <para>Delete all files from the current directory that are
1107 normally created by building the program. Don't delete
1108 the files that record the configuration, or files
1109 generated by <command>gmake boot</command>. Also preserve
1110 files that could be made by building, but normally aren't
1111 because the distribution comes with them.</para>
1116 <term><literal>distclean</literal></term>
1118 <para>Delete all files from the current directory that are
1119 created by configuring or building the program. If you
1120 have unpacked the source and built the program without
1121 creating any other files, <literal>make
1122 distclean</literal> should leave only the files that were
1123 in the distribution.</para>
1128 <term><literal>mostlyclean</literal></term>
1130 <para>Like <literal>clean</literal>, but may refrain from
1131 deleting a few files that people normally don't want to
1137 <term><literal>maintainer-clean</literal></term>
1139 <para>Delete everything from the current directory that
1140 can be reconstructed with this Makefile. This typically
1141 includes everything deleted by
1142 <literal>distclean</literal>, plus more: C source files
1143 produced by Bison, tags tables, Info files, and so
1146 <para>One exception, however: <literal>make
1147 maintainer-clean</literal> should not delete
1148 <filename>configure</filename> even if
1149 <filename>configure</filename> can be remade using a rule
1150 in the <filename>Makefile</filename>. More generally,
1151 <literal>make maintainer-clean</literal> should not delete
1152 anything that needs to exist in order to run
1153 <filename>configure</filename> and then begin to build the
1159 <term><literal>check</literal></term>
1161 <para>run the test suite.</para>
1166 <para>All of these standard targets automatically recurse into
1167 sub-directories. Certain other standard targets do not:</para>
1171 <term><literal>configure</literal></term>
1173 <para>is only available in the root directory
1174 <constant>$(FPTOOLS_TOP)</constant>; it has
1175 been discussed in <xref
1176 linkend="sec-build-config"/>.</para>
1181 <term><literal>depend</literal></term>
1183 <para>make a <filename>.depend</filename> file in each
1184 directory that needs it. This <filename>.depend</filename>
1185 file contains mechanically-generated dependency
1186 information; for example, suppose a directory contains a
1187 Haskell source module <filename>Foo.lhs</filename> which
1188 imports another module <literal>Baz</literal>. Then the
1189 generated <filename>.depend</filename> file will contain
1190 the dependency:</para>
1192 <programlisting>Foo.o : Baz.hi</programlisting>
1194 <para>which says that the object file
1195 <filename>Foo.o</filename> depends on the interface file
1196 <filename>Baz.hi</filename> generated by compiling module
1197 <literal>Baz</literal>. The <filename>.depend</filename>
1198 file is automatically included by every Makefile.</para>
1203 <term><literal>binary-dist</literal></term>
1205 <para>make a binary distribution. This is the target we
1206 use to build the binary distributions of GHC and
1212 <term><literal>dist</literal></term>
1214 <para>make a source distribution. Note that this target
1215 does “make distclean” as part of its work;
1216 don't use it if you want to keep what you've built.</para>
1221 <para>Most <filename>Makefile</filename>s have targets other
1222 than these. You can discover them by looking in the
1223 <filename>Makefile</filename> itself.</para>
1227 <title>Using a project from the build tree</title>
1229 <para>If you want to build GHC (say) and just use it direct from
1230 the build tree without doing <literal>make install</literal>
1231 first, you can run the in-place driver script:
1232 <filename>ghc/compiler/ghc-inplace</filename>.</para>
1234 <para> Do <emphasis>NOT</emphasis> use
1235 <filename>ghc/compiler/ghc</filename>, or
1236 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
1237 scripts intended for installation, and contain hard-wired paths
1238 to the installed libraries, rather than the libraries in the
1241 <para>Happy can similarly be run from the build tree, using
1242 <filename>happy/src/happy-inplace</filename>, and similarly for
1243 Alex and Haddock.</para>
1247 <title>Fast Making</title>
1249 <indexterm><primary>fastmake</primary></indexterm>
1250 <indexterm><primary>dependencies, omitting</primary></indexterm>
1251 <indexterm><primary>FAST, makefile variable</primary></indexterm>
1253 <para>Sometimes the dependencies get in the way: if you've made
1254 a small change to one file, and you're absolutely sure that it
1255 won't affect anything else, but you know that
1256 <command>make</command> is going to rebuild everything anyway,
1257 the following hack may be useful:</para>
1259 <screen>$ gmake FAST=YES</screen>
1261 <para>This tells the make system to ignore dependencies and just
1262 build what you tell it to. In other words, it's equivalent to
1263 temporarily removing the <filename>.depend</filename> file in
1264 the current directory (where <command>mkdependHS</command> and
1265 friends store their dependency information).</para>
1267 <para>A bit of history: GHC used to come with a
1268 <command>fastmake</command> script that did the above job, but
1269 GNU make provides the features we need to do it without
1270 resorting to a script. Also, we've found that fastmaking is
1271 less useful since the advent of GHC's recompilation checker (see
1272 the User's Guide section on "Separate Compilation").</para>
1276 <sect1 id="sec-makefile-arch">
1277 <title>The <filename>Makefile</filename> architecture</title>
1278 <indexterm><primary>makefile architecture</primary></indexterm>
1280 <para><command>make</command> is great if everything
1281 works—you type <command>gmake install</command> and lo! the
1282 right things get compiled and installed in the right places. Our
1283 goal is to make this happen often, but somehow it often doesn't;
1284 instead some weird error message eventually emerges from the
1285 bowels of a directory you didn't know existed.</para>
1287 <para>The purpose of this section is to give you a road-map to
1288 help you figure out what is going right and what is going
1292 <title>Debugging</title>
1294 <para>Debugging <filename>Makefile</filename>s is something of a
1295 black art, but here's a couple of tricks that we find
1296 particularly useful. The following command allows you to see
1297 the contents of any make variable in the context of the current
1298 <filename>Makefile</filename>:</para>
1300 <screen>$ make show VALUE=HS_SRCS</screen>
1302 <para>where you can replace <literal>HS_SRCS</literal> with the
1303 name of any variable you wish to see the value of.</para>
1305 <para>GNU make has a <option>-d</option> option which generates
1306 a dump of the decision procedure used to arrive at a conclusion
1307 about which files should be recompiled. Sometimes useful for
1308 tracking down problems with superfluous or missing
1309 recompilations.</para>
1313 <title>A small project</title>
1315 <para>To get started, let us look at the
1316 <filename>Makefile</filename> for an imaginary small
1317 <literal>fptools</literal> project, <literal>small</literal>.
1318 Each project in <literal>fptools</literal> has its own directory
1319 in <constant>FPTOOLS_TOP</constant>, so the
1320 <literal>small</literal> project will have its own directory
1321 <constant>FPOOLS_TOP/small/</constant>. Inside the
1322 <filename>small/</filename> directory there will be a
1323 <filename>Makefile</filename>, looking something like
1326 <indexterm><primary>Makefile, minimal</primary></indexterm>
1328 <programlisting># Makefile for fptools project "small"
1331 include $(TOP)/mk/boilerplate.mk
1333 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1336 include $(TOP)/target.mk</programlisting>
1338 <para>this <filename>Makefile</filename> has three
1343 <para>The first section includes
1346 One of the most important
1347 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
1348 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
1353 a file of “boilerplate” code from the level
1354 above (which in this case will be
1355 <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
1356 As its name suggests, <filename>boilerplate.mk</filename>
1357 consists of a large quantity of standard
1358 <filename>Makefile</filename> code. We discuss this
1359 boilerplate in more detail in <xref linkend="sec-boiler"/>.
1360 <indexterm><primary>include, directive in
1361 Makefiles</primary></indexterm> <indexterm><primary>Makefile
1362 inclusion</primary></indexterm></para>
1364 <para>Before the <literal>include</literal> statement, you
1365 must define the <command>make</command> variable
1366 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
1367 to be the directory containing the <filename>mk</filename>
1368 directory in which the <filename>boilerplate.mk</filename>
1369 file is. It is <emphasis>not</emphasis> OK to simply say</para>
1371 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
1374 <para>Why? Because the <filename>boilerplate.mk</filename>
1375 file needs to know where it is, so that it can, in turn,
1376 <literal>include</literal> other files. (Unfortunately,
1377 when an <literal>include</literal>d file does an
1378 <literal>include</literal>, the filename is treated relative
1379 to the directory in which <command>gmake</command> is being
1380 run, not the directory in which the
1381 <literal>include</literal>d sits.) In general,
1382 <emphasis>every file <filename>foo.mk</filename> assumes
1384 <filename>$(TOP)/mk/foo.mk</filename>
1385 refers to itself.</emphasis> It is up to the
1386 <filename>Makefile</filename> doing the
1387 <literal>include</literal> to ensure this is the case.</para>
1389 <para>Files intended for inclusion in other
1390 <filename>Makefile</filename>s are written to have the
1391 following property: <emphasis>after
1392 <filename>foo.mk</filename> is <literal>include</literal>d,
1393 it leaves <constant>TOP</constant> containing the same value
1394 as it had just before the <literal>include</literal>
1395 statement</emphasis>. In our example, this invariant
1396 guarantees that the <literal>include</literal> for
1397 <filename>target.mk</filename> will look in the same
1398 directory as that for <filename>boilerplate.mk</filename>.</para>
1402 <para> The second section defines the following standard
1403 <command>make</command> variables:
1404 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
1405 (the source files from which is to be built), and
1406 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
1407 (the executable binary to be built). We will discuss in
1408 more detail what the “standard variables” are,
1409 and how they affect what happens, in <xref
1410 linkend="sec-targets"/>.</para>
1412 <para>The definition for <constant>SRCS</constant> uses the
1413 useful GNU <command>make</command> construct
1414 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
1415 which expands to a list of all the files matching the
1416 pattern <literal>pat</literal> in the current directory. In
1417 this example, <constant>SRCS</constant> is set to the list
1418 of all the <filename>.lhs</filename> and
1419 <filename>.c</filename> files in the directory. (Let's
1420 suppose there is one of each, <filename>Foo.lhs</filename>
1421 and <filename>Baz.c</filename>.)</para>
1425 <para>The last section includes a second file of standard
1427 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
1428 It contains the rules that tell <command>gmake</command> how
1429 to make the standard targets (<xref
1430 linkend="sec-standard-targets"/>). Why, you ask, can't this
1431 standard code be part of
1432 <filename>boilerplate.mk</filename>? Good question. We
1433 discuss the reason later, in <xref
1434 linkend="sec-boiler-arch"/>.</para>
1436 <para>You do not <emphasis>have</emphasis> to
1437 <literal>include</literal> the
1438 <filename>target.mk</filename> file. Instead, you can write
1439 rules of your own for all the standard targets. Usually,
1440 though, you will find quite a big payoff from using the
1441 canned rules in <filename>target.mk</filename>; the price
1442 tag is that you have to understand what canned rules get
1443 enabled, and what they do (<xref
1444 linkend="sec-targets"/>).</para>
1448 <para>In our example <filename>Makefile</filename>, most of the
1449 work is done by the two <literal>include</literal>d files. When
1450 you say <command>gmake all</command>, the following things
1455 <para><command>gmake</command> figures out that the object
1456 files are <filename>Foo.o</filename> and
1457 <filename>Baz.o</filename>.</para>
1461 <para>It uses a boilerplate pattern rule to compile
1462 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
1463 using a Haskell compiler. (Which one? That is set in the
1464 build configuration.)</para>
1468 <para>It uses another standard pattern rule to compile
1469 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
1470 using a C compiler. (Ditto.)</para>
1474 <para>It links the resulting <filename>.o</filename> files
1475 together to make <literal>small</literal>, using the Haskell
1476 compiler to do the link step. (Why not use
1477 <command>ld</command>? Because the Haskell compiler knows
1478 what standard libraries to link in. How did
1479 <command>gmake</command> know to use the Haskell compiler to
1480 do the link, rather than the C compiler? Because we set the
1481 variable <constant>HS_PROG</constant> rather than
1482 <constant>C_PROG</constant>.)</para>
1486 <para>All <filename>Makefile</filename>s should follow the above
1487 three-section format.</para>
1491 <title>A larger project</title>
1493 <para>Larger projects are usually structured into a number of
1494 sub-directories, each of which has its own
1495 <filename>Makefile</filename>. (In very large projects, this
1496 sub-structure might be iterated recursively, though that is
1497 rare.) To give you the idea, here's part of the directory
1498 structure for the (rather large) GHC project:</para>
1500 <programlisting>$(FPTOOLS_TOP)/ghc/
1507 ...source files for documentation...
1510 ...source files for driver...
1513 parser/...source files for parser...
1514 renamer/...source files for renamer...
1515 ...etc...</programlisting>
1517 <para>The sub-directories <filename>docs</filename>,
1518 <filename>driver</filename>, <filename>compiler</filename>, and
1519 so on, each contains a sub-component of GHC, and each has its
1520 own <filename>Makefile</filename>. There must also be a
1521 <filename>Makefile</filename> in
1522 <filename>$(FPTOOLS_TOP)/ghc</filename>.
1523 It does most of its work by recursively invoking
1524 <command>gmake</command> on the <filename>Makefile</filename>s
1525 in the sub-directories. We say that
1526 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
1527 <filename>Makefile</filename></emphasis>, because it does little
1528 except organise its children, while the
1529 <filename>Makefile</filename>s in the sub-directories are all
1530 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
1531 principle the sub-directories might themselves contain a
1532 non-leaf <filename>Makefile</filename> and several
1533 sub-sub-directories, but that does not happen in GHC.)</para>
1535 <para>The <filename>Makefile</filename> in
1536 <filename>ghc/compiler</filename> is considered a leaf
1537 <filename>Makefile</filename> even though the
1538 <filename>ghc/compiler</filename> has sub-directories, because
1539 these sub-directories do not themselves have
1540 <filename>Makefile</filename>s in them. They are just used to
1541 structure the collection of modules that make up GHC, but all
1542 are managed by the single <filename>Makefile</filename> in
1543 <filename>ghc/compiler</filename>.</para>
1545 <para>You will notice that <filename>ghc/</filename> also
1546 contains a directory <filename>ghc/mk/</filename>. It contains
1547 GHC-specific <filename>Makefile</filename> boilerplate code.
1548 More precisely:</para>
1552 <para><filename>ghc/mk/boilerplate.mk</filename> is included
1553 at the top of <filename>ghc/Makefile</filename>, and of all
1554 the leaf <filename>Makefile</filename>s in the
1555 sub-directories. It in turn <literal>include</literal>s the
1556 main boilerplate file
1557 <filename>mk/boilerplate.mk</filename>.</para>
1561 <para><filename>ghc/mk/target.mk</filename> is
1562 <literal>include</literal>d at the bottom of
1563 <filename>ghc/Makefile</filename>, and of all the leaf
1564 <filename>Makefile</filename>s in the sub-directories. It
1565 in turn <literal>include</literal>s the file
1566 <filename>mk/target.mk</filename>.</para>
1570 <para>So these two files are the place to look for GHC-wide
1571 customisation of the standard boilerplate.</para>
1574 <sect2 id="sec-boiler-arch">
1575 <title>Boilerplate architecture</title>
1576 <indexterm><primary>boilerplate architecture</primary></indexterm>
1578 <para>Every <filename>Makefile</filename> includes a
1579 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
1580 file at the top, and
1581 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
1582 file at the bottom. In this section we discuss what is in these
1583 files, and why there have to be two of them. In general:</para>
1587 <para><filename>boilerplate.mk</filename> consists of:</para>
1591 <para><emphasis>Definitions of millions of
1592 <command>make</command> variables</emphasis> that
1593 collectively specify the build configuration. Examples:
1594 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1595 the options to feed to the Haskell compiler;
1596 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
1597 the sub-directories to enable within the
1598 <literal>nofib</literal> project;
1599 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
1600 the name of the Haskell compiler to use when compiling
1601 GHC in the <literal>ghc</literal> project.</para>
1605 <para><emphasis>Standard pattern rules</emphasis> that
1606 tell <command>gmake</command> how to construct one file
1607 from another.</para>
1611 <para><filename>boilerplate.mk</filename> needs to be
1612 <literal>include</literal>d at the <emphasis>top</emphasis>
1613 of each <filename>Makefile</filename>, so that the user can
1614 replace the boilerplate definitions or pattern rules by
1615 simply giving a new definition or pattern rule in the
1616 <filename>Makefile</filename>. <command>gmake</command>
1617 simply takes the last definition as the definitive one.</para>
1619 <para>Instead of <emphasis>replacing</emphasis> boilerplate
1620 definitions, it is also quite common to
1621 <emphasis>augment</emphasis> them. For example, a
1622 <filename>Makefile</filename> might say:</para>
1624 <programlisting>SRC_HC_OPTS += -O</programlisting>
1626 <para>thereby adding “<option>-O</option>” to
1628 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
1632 <para><filename>target.mk</filename> contains
1633 <command>make</command> rules for the standard targets
1634 described in <xref linkend="sec-standard-targets"/>. These
1635 rules are selectively included, depending on the setting of
1636 certain <command>make</command> variables. These variables
1637 are usually set in the middle section of the
1638 <filename>Makefile</filename> between the two
1639 <literal>include</literal>s.</para>
1641 <para><filename>target.mk</filename> must be included at the
1642 end (rather than being part of
1643 <filename>boilerplate.mk</filename>) for several tiresome
1649 <para><command>gmake</command> commits target and
1650 dependency lists earlier than it should. For example,
1651 <filename>target.mk</filename> has a rule that looks
1654 <programlisting>$(HS_PROG) : $(OBJS)
1655 $(HC) $(LD_OPTS) $< -o $@</programlisting>
1657 <para>If this rule was in
1658 <filename>boilerplate.mk</filename> then
1659 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
1661 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
1662 would not have their final values at the moment
1663 <command>gmake</command> encountered the rule. Alas,
1664 <command>gmake</command> takes a snapshot of their
1665 current values, and wires that snapshot into the rule.
1666 (In contrast, the commands executed when the rule
1667 “fires” are only substituted at the moment
1668 of firing.) So, the rule must follow the definitions
1669 given in the <filename>Makefile</filename> itself.</para>
1673 <para>Unlike pattern rules, ordinary rules cannot be
1674 overriden or replaced by subsequent rules for the same
1675 target (at least, not without an error message).
1676 Including ordinary rules in
1677 <filename>boilerplate.mk</filename> would prevent the
1678 user from writing rules for specific targets in specific
1683 <para>There are a couple of other reasons I've
1684 forgotten, but it doesn't matter too much.</para>
1691 <sect2 id="sec-boiler">
1692 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
1693 <indexterm><primary>boilerplate.mk</primary></indexterm>
1695 <para>If you look at
1696 <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
1697 you will find that it consists of the following sections, each
1698 held in a separate file:</para>
1702 <term><filename>config.mk</filename>
1703 <indexterm><primary>config.mk</primary></indexterm>
1706 <para>is the build configuration file we discussed at
1707 length in <xref linkend="sec-build-config"/>.</para>
1712 <term><filename>paths.mk</filename>
1713 <indexterm><primary>paths.mk</primary></indexterm>
1716 <para>defines <command>make</command> variables for
1717 pathnames and file lists. This file contains code for
1718 automatically compiling lists of source files and deriving
1719 lists of object files from those. The results can be
1720 overriden in the <filename>Makefile</filename>, but in
1721 most cases the automatic setup should do the right
1724 <para>The following variables may be set in the
1725 <filename>Makefile</filename> to affect how the automatic
1726 source file search is done:</para>
1730 <term><literal>ALL_DIRS</literal>
1731 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
1734 <para>Set to a list of directories to search in
1735 addition to the current directory for source
1741 <term><literal>EXCLUDED_SRCS</literal>
1742 <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
1745 <para>Set to a list of source files (relative to the
1746 current directory) to omit from the automatic
1747 search. The source searching machinery is clever
1748 enough to know that if you exclude a source file
1749 from which other sources are derived, then the
1750 derived sources should also be excluded. For
1751 example, if you set <literal>EXCLUDED_SRCS</literal>
1752 to include <filename>Foo.y</filename>, then
1753 <filename>Foo.hs</filename> will also be
1759 <term><literal>EXTRA_SRCS</literal>
1760 <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
1763 <para>Set to a list of extra source files (perhaps
1764 in directories not listed in
1765 <literal>ALL_DIRS</literal>) that should be
1771 <para>The results of the automatic source file search are
1772 placed in the following make variables:</para>
1776 <term><literal>SRCS</literal>
1777 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
1780 <para>All source files found, sorted and without
1781 duplicates, including those which might not exist
1782 yet but will be derived from other existing sources.
1783 <literal>SRCS</literal> <emphasis>can</emphasis> be
1784 overriden if necessary, in which case the variables
1785 below will follow suit.</para>
1790 <term><literal>HS_SRCS</literal>
1791 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
1794 <para>all Haskell source files in the current
1795 directory, including those derived from other source
1796 files (eg. Happy sources also give rise to Haskell
1802 <term><literal>HS_OBJS</literal>
1803 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
1806 <para>Object files derived from
1807 <literal>HS_SRCS</literal>.</para>
1812 <term><literal>HS_IFACES</literal>
1813 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
1816 <para>Interface files (<literal>.hi</literal> files)
1817 derived from <literal>HS_SRCS</literal>.</para>
1822 <term><literal>C_SRCS</literal>
1823 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
1826 <para>All C source files found.</para>
1831 <term><literal>C_OBJS</literal>
1832 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
1835 <para>Object files derived from
1836 <literal>C_SRCS</literal>.</para>
1841 <term><literal>SCRIPT_SRCS</literal>
1842 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
1845 <para>All script source files found
1846 (<literal>.lprl</literal> files).</para>
1851 <term><literal>SCRIPT_OBJS</literal>
1852 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
1855 <para><quote>object</quote> files derived from
1856 <literal>SCRIPT_SRCS</literal>
1857 (<literal>.prl</literal> files).</para>
1862 <term><literal>HSC_SRCS</literal>
1863 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
1866 <para>All <literal>hsc2hs</literal> source files
1867 (<literal>.hsc</literal> files).</para>
1872 <term><literal>HAPPY_SRCS</literal>
1873 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
1876 <para>All <literal>happy</literal> source files
1877 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
1882 <term><literal>OBJS</literal>
1883 <indexterm><primary>OBJS</primary></indexterm>
1886 <para>the concatenation of
1887 <literal>$(HS_OBJS)</literal>,
1888 <literal>$(C_OBJS)</literal>, and
1889 <literal>$(SCRIPT_OBJS)</literal>.</para>
1894 <para>Any or all of these definitions can easily be
1895 overriden by giving new definitions in your
1896 <filename>Makefile</filename>.</para>
1898 <para>What, exactly, does <filename>paths.mk</filename>
1899 consider a <quote>source file</quote> to be? It's based
1900 on the file's suffix (e.g. <filename>.hs</filename>,
1901 <filename>.lhs</filename>, <filename>.c</filename>,
1902 <filename>.hy</filename>, etc), but this is the kind of
1903 detail that changes, so rather than enumerate the source
1904 suffices here the best thing to do is to look in
1905 <filename>paths.mk</filename>.</para>
1910 <term><filename>opts.mk</filename>
1911 <indexterm><primary>opts.mk</primary></indexterm>
1914 <para>defines <command>make</command> variables for option
1915 strings to pass to each program. For example, it defines
1916 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1917 the option strings to pass to the Haskell compiler. See
1918 <xref linkend="sec-suffix"/>.</para>
1923 <term><filename>suffix.mk</filename>
1924 <indexterm><primary>suffix.mk</primary></indexterm>
1927 <para>defines standard pattern rules—see <xref
1928 linkend="sec-suffix"/>.</para>
1933 <para>Any of the variables and pattern rules defined by the
1934 boilerplate file can easily be overridden in any particular
1935 <filename>Makefile</filename>, because the boilerplate
1936 <literal>include</literal> comes first. Definitions after this
1937 <literal>include</literal> directive simply override the default
1938 ones in <filename>boilerplate.mk</filename>.</para>
1941 <sect2 id="sec-platforms">
1942 <title>Platform settings</title>
1943 <indexterm><primary>Platform settings</primary>
1946 <para>There are three platforms of interest when building GHC:</para>
1950 <term>The <emphasis>build</emphasis> platform</term>
1952 <para>The platform on which we are doing this build.</para>
1957 <term>The <emphasis>host</emphasis> platform</term>
1959 <para>The platform on which these binaries will run.</para>
1964 <term>The <emphasis>target</emphasis> platform</term>
1966 <para>The platform for which this compiler will generate code.</para>
1971 <para>These platforms are set when running the
1972 <literal>configure</literal> script, using the
1973 <option>--build</option>, <option>--host</option>, and
1974 <option>--target</option> options. The <filename>mk/config.mk</filename>
1975 file defines several symbols related to the platform settings (see
1976 <filename>mk/config.mk</filename> for details).</para>
1978 <para>We don't currently support build & host being different, because
1979 the build process creates binaries that are both run during the build,
1980 and also installed.</para>
1982 <para>If host and target are different, then we are building a
1983 cross-compiler. For GHC, this means a compiler
1984 which will generate intermediate .hc files to port to the target
1985 architecture for bootstrapping. The libraries and stage 2 compiler
1986 will be built as HC files for the target system (see <xref
1987 linkend="sec-porting-ghc" /> for details.</para>
1989 <para>More details on when to use BUILD, HOST or TARGET can be found in
1990 the comments in <filename>config.mk</filename>.</para>
1993 <sect2 id="sec-suffix">
1994 <title>Pattern rules and options</title>
1995 <indexterm><primary>Pattern rules</primary></indexterm>
1998 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
1999 defines standard <emphasis>pattern rules</emphasis> that say how
2000 to build one kind of file from another, for example, how to
2001 build a <filename>.o</filename> file from a
2002 <filename>.c</filename> file. (GNU <command>make</command>'s
2003 <emphasis>pattern rules</emphasis> are more powerful and easier
2004 to use than Unix <command>make</command>'s <emphasis>suffix
2005 rules</emphasis>.)</para>
2007 <para>Almost all the rules look something like this:</para>
2009 <programlisting>%.o : %.c
2011 $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
2013 <para>Here's how to understand the rule. It says that
2014 <emphasis>something</emphasis><filename>.o</filename> (say
2015 <filename>Foo.o</filename>) can be built from
2016 <emphasis>something</emphasis><filename>.c</filename>
2017 (<filename>Foo.c</filename>), by invoking the C compiler (path
2018 name held in <constant>$(CC)</constant>), passing to it
2019 the options <constant>$(CC_OPTS)</constant> and
2020 the rule's dependent file of the rule
2021 <literal>$<</literal> (<filename>Foo.c</filename> in
2022 this case), and putting the result in the rule's target
2023 <literal>$@</literal> (<filename>Foo.o</filename> in this
2026 <para>Every program is held in a <command>make</command>
2027 variable defined in <filename>mk/config.mk</filename>—look
2028 in <filename>mk/config.mk</filename> for the complete list. One
2029 important one is the Haskell compiler, which is called
2030 <constant>$(HC)</constant>.</para>
2032 <para>Every program's options are are held in a
2033 <command>make</command> variables called
2034 <constant><prog>_OPTS</constant>. the
2035 <constant><prog>_OPTS</constant> variables are
2036 defined in <filename>mk/opts.mk</filename>. Almost all of them
2037 are defined like this:</para>
2039 <programlisting>CC_OPTS = \
2040 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
2042 <para>The four variables from which
2043 <constant>CC_OPTS</constant> is built have the following
2048 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
2050 <para>options passed to all C compilations.</para>
2055 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
2057 <para>options passed to C compilations for way
2058 <literal><way></literal>. For example,
2059 <constant>WAY_mp_CC_OPTS</constant>
2060 gives options to pass to the C compiler when compiling way
2061 <literal>mp</literal>. The variable
2062 <constant>WAY_CC_OPTS</constant> holds
2063 options to pass to the C compiler when compiling the
2064 standard way. (<xref linkend="sec-ways"/> dicusses
2065 multi-way compilation.)</para>
2070 <term><constant><module>_CC_OPTS</constant>:</term>
2072 <para>options to pass to the C compiler that are specific
2073 to module <literal><module></literal>. For example,
2074 <constant>SMap_CC_OPTS</constant> gives the
2075 specific options to pass to the C compiler when compiling
2076 <filename>SMap.c</filename>.</para>
2081 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
2083 <para>extra options to pass to all C compilations. This
2084 is intended for command line use, thus:</para>
2086 <screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
2092 <sect2 id="sec-targets">
2093 <title>The main <filename>mk/target.mk</filename> file</title>
2094 <indexterm><primary>target.mk</primary></indexterm>
2096 <para><filename>target.mk</filename> contains canned rules for
2097 all the standard targets described in <xref
2098 linkend="sec-standard-targets"/>. It is complicated by the fact
2099 that you don't want all of these rules to be active in every
2100 <filename>Makefile</filename>. Rather than have a plethora of
2101 tiny files which you can include selectively, there is a single
2102 file, <filename>target.mk</filename>, which selectively includes
2103 rules based on whether you have defined certain variables in
2104 your <filename>Makefile</filename>. This section explains what
2105 rules you get, what variables control them, and what the rules
2106 do. Hopefully, you will also get enough of an idea of what is
2107 supposed to happen that you can read and understand any weird
2108 special cases yourself.</para>
2112 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
2114 <para>If <constant>HS_PROG</constant> is defined,
2115 you get rules with the following targets:</para>
2119 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
2121 <para>itself. This rule links
2122 <constant>$(OBJS)</constant> with the Haskell
2123 runtime system to get an executable called
2124 <constant>$(HS_PROG)</constant>.</para>
2129 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
2132 <constant>$(HS_PROG)</constant> in
2133 <constant>$(bindir)</constant>.</para>
2142 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
2144 <para>is similar to <constant>HS_PROG</constant>,
2145 except that the link step links
2146 <constant>$(C_OBJS)</constant> with the C
2147 runtime system.</para>
2152 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
2154 <para>is similar to <constant>HS_PROG</constant>,
2155 except that it links
2156 <constant>$(LIB_OBJS)</constant> to make the
2157 library archive <constant>$(LIBRARY)</constant>,
2158 and <literal>install</literal> installs it in
2159 <constant>$(libdir)</constant>.</para>
2164 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
2166 <para>…</para>
2171 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
2173 <para>…</para>
2178 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
2180 <para>If <constant>HS_SRCS</constant> is defined
2181 and non-empty, a rule for the target
2182 <literal>depend</literal> is included, which generates
2183 dependency information for Haskell programs. Similarly
2184 for <constant>C_SRCS</constant>.</para>
2189 <para>All of these rules are “double-colon” rules,
2192 <programlisting>install :: $(HS_PROG)
2193 ...how to install it...</programlisting>
2195 <para>GNU <command>make</command> treats double-colon rules as
2196 separate entities. If there are several double-colon rules for
2197 the same target it takes each in turn and fires it if its
2198 dependencies say to do so. This means that you can, for
2199 example, define both <constant>HS_PROG</constant> and
2200 <constant>LIBRARY</constant>, which will generate two rules for
2201 <literal>install</literal>. When you type <command>gmake
2202 install</command> both rules will be fired, and both the program
2203 and the library will be installed, just as you wanted.</para>
2206 <sect2 id="sec-subdirs">
2207 <title>Recursion</title>
2208 <indexterm><primary>recursion, in makefiles</primary></indexterm>
2209 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
2211 <para>In leaf <filename>Makefile</filename>s the variable
2212 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
2213 is undefined. In non-leaf <filename>Makefile</filename>s,
2214 <constant>SUBDIRS</constant> is set to the list of
2215 sub-directories that contain subordinate
2216 <filename>Makefile</filename>s. <emphasis>It is up to you to
2217 set <constant>SUBDIRS</constant> in the
2218 <filename>Makefile</filename>.</emphasis> There is no automation
2219 here—<constant>SUBDIRS</constant> is too important to
2222 <para>When <constant>SUBDIRS</constant> is defined,
2223 <filename>target.mk</filename> includes a rather neat rule for
2224 the standard targets (<xref linkend="sec-standard-targets"/> that
2225 simply invokes <command>make</command> recursively in each of
2226 the sub-directories.</para>
2228 <para><emphasis>These recursive invocations are guaranteed to
2229 occur in the order in which the list of directories is specified
2230 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
2231 be important. For example, when you say <command>gmake
2232 boot</command> it can be important that the recursive invocation
2233 of <command>make boot</command> is done in one sub-directory
2234 (the include files, say) before another (the source files).
2235 Generally, put the most independent sub-directory first, and the
2236 most dependent last.</para>
2239 <sect2 id="sec-ways">
2240 <title>Way management</title>
2241 <indexterm><primary>way management</primary></indexterm>
2243 <para>We sometimes want to build essentially the same system in
2244 several different “ways”. For example, we want to build GHC's
2245 <literal>Prelude</literal> libraries with and without profiling,
2246 so that there is an appropriately-built library archive to link
2247 with when the user compiles his program. It would be possible
2248 to have a completely separate build tree for each such “way”,
2249 but it would be horribly bureaucratic, especially since often
2250 only parts of the build tree need to be constructed in multiple
2254 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2255 contains some clever magic to allow you to build several
2256 versions of a system; and to control locally how many versions
2257 are built and how they differ. This section explains the
2260 <para>The files for a particular way are distinguished by
2261 munging the suffix. The <quote>normal way</quote> is always
2262 built, and its files have the standard suffices
2263 <filename>.o</filename>, <filename>.hi</filename>, and so on.
2264 In addition, you can build one or more extra ways, each
2265 distinguished by a <emphasis>way tag</emphasis>. The object
2266 files and interface files for one of these extra ways are
2267 distinguished by their suffix. For example, way
2268 <literal>mp</literal> has files
2269 <filename>.mp_o</filename> and
2270 <filename>.mp_hi</filename>. Library archives have their
2271 way tag the other side of the dot, for boring reasons; thus,
2272 <filename>libHS_mp.a</filename>.</para>
2274 <para>A <command>make</command> variable called
2275 <constant>way</constant> holds the current way tag.
2276 <emphasis><constant>way</constant> is only ever set on the
2277 command line of <command>gmake</command></emphasis> (usually in
2278 a recursive invocation of <command>gmake</command> by the
2279 system). It is never set inside a
2280 <filename>Makefile</filename>. So it is a global constant for
2281 any one invocation of <command>gmake</command>. Two other
2282 <command>make</command> variables,
2283 <constant>way_</constant> and
2284 <constant>_way</constant> are immediately derived from
2285 <constant>$(way)</constant> and never altered. If
2286 <constant>way</constant> is not set, then neither are
2287 <constant>way_</constant> and
2288 <constant>_way</constant>, and the invocation of
2289 <command>make</command> will build the <quote>normal
2290 way</quote>. If <constant>way</constant> is set, then the other
2291 two variables are set in sympathy. For example, if
2292 <constant>$(way)</constant> is “<literal>mp</literal>”,
2293 then <constant>way_</constant> is set to
2294 “<literal>mp_</literal>” and
2295 <constant>_way</constant> is set to
2296 “<literal>_mp</literal>”. These three variables are
2297 then used when constructing file names.</para>
2299 <para>So how does <command>make</command> ever get recursively
2300 invoked with <constant>way</constant> set? There are two ways
2301 in which this happens:</para>
2305 <para>For some (but not all) of the standard targets, when
2306 in a leaf sub-directory, <command>make</command> is
2307 recursively invoked for each way tag in
2308 <constant>$(WAYS)</constant>. You set
2309 <constant>WAYS</constant> in the
2310 <filename>Makefile</filename> to the list of way tags you
2311 want these targets built for. The mechanism here is very
2312 much like the recursive invocation of
2313 <command>make</command> in sub-directories (<xref
2314 linkend="sec-subdirs"/>). It is up to you to set
2315 <constant>WAYS</constant> in your
2316 <filename>Makefile</filename>; this is how you control what
2317 ways will get built.</para>
2321 <para>For a useful collection of targets (such as
2322 <filename>libHS_mp.a</filename>,
2323 <filename>Foo.mp_o</filename>) there is a rule which
2324 recursively invokes <command>make</command> to make the
2325 specified target, setting the <constant>way</constant>
2326 variable. So if you say <command>gmake
2327 Foo.mp_o</command> you should see a recursive
2328 invocation <command>gmake Foo.mp_o way=mp</command>,
2329 and <emphasis>in this recursive invocation the pattern rule
2330 for compiling a Haskell file into a <filename>.o</filename>
2331 file will match</emphasis>. The key pattern rules (in
2332 <filename>suffix.mk</filename>) look like this:
2334 <programlisting>%.$(way_)o : %.lhs
2335 $(HC) $(HC_OPTS) $< -o $@</programlisting>
2341 <para>You can invoke <command>make</command> with a
2342 particular <literal>way</literal> setting yourself, in order
2343 to build files related to a particular
2344 <literal>way</literal> in the current directory. eg.
2346 <screen>$ make way=p</screen>
2348 will build files for the profiling way only in the current
2355 <title>When the canned rule isn't right</title>
2357 <para>Sometimes the canned rule just doesn't do the right thing.
2358 For example, in the <literal>nofib</literal> suite we want the
2359 link step to print out timing information. The thing to do here
2360 is <emphasis>not</emphasis> to define
2361 <constant>HS_PROG</constant> or
2362 <constant>C_PROG</constant>, and instead define a special
2363 purpose rule in your own <filename>Makefile</filename>. By
2364 using different variable names you will avoid the canned rules
2365 being included, and conflicting with yours.</para>
2369 <sect1 id="building-docs">
2370 <title>Building the documentation</title>
2372 <sect2 id="pre-supposed-doc-tools">
2373 <title>Tools for building the Documentation</title>
2375 <para>The following additional tools are required if you want to
2376 format the documentation that comes with the
2377 <literal>fptools</literal> projects:</para>
2382 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
2383 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
2386 <para>Much of our documentation is written in DocBook XML, instructions
2387 on installing and configuring the DocBook tools are below.</para>
2393 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
2394 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
2397 <para>A decent TeX distribution is required if you want to
2398 produce printable documentation. We recomment teTeX,
2399 which includes just about everything you need.</para>
2405 <indexterm><primary>Haddock</primary></indexterm>
2408 <para>Haddock is a Haskell documentation tool that we use
2409 for automatically generating documentation from the
2410 library source code. It is an <literal>fptools</literal>
2411 project in itself. To build documentation for the
2412 libraries (<literal>fptools/libraries</literal>) you
2413 should check out and build Haddock in
2414 <literal>fptools/haddock</literal>. Haddock requires GHC
2422 <title>Installing the DocBook tools</title>
2425 <title>Installing the DocBook tools on Linux</title>
2427 <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
2428 you probably have working DocBook tools already installed. The
2429 configure script should detect your setup and you're away.</para>
2431 <para>If you don't have DocBook tools installed, and you are
2432 using a system that can handle RPM packages, you can use <ulink
2433 url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
2434 packages for your system. Search for the packages
2435 <literal>docbook-dtd</literal>,
2436 <literal>docbook-xsl-stylesheets</literal>,
2437 <literal>libxslt</literal>,
2438 <literal>libxml2</literal>,
2439 <literal>fop</literal>,
2440 <literal>xmltex</literal>, and
2441 <literal>dvips</literal>.</para>
2445 <title>Installing DocBook on FreeBSD</title>
2447 <para>On FreeBSD systems, the easiest way to get DocBook up
2448 and running is to install it from the ports tree or a
2449 pre-compiled package (packages are available from your local
2450 FreeBSD mirror site).</para>
2452 <para>To use the ports tree, do this:
2453 <screen>$ cd /usr/ports/textproc/docproj
2454 $ make install</screen>
2455 This installs the FreeBSD documentation project tools, which
2456 includes everything needed to format the GHC
2457 documentation.</para>
2461 <title>Installing from binaries on Windows</title>
2463 <para>Probably the fastest route to a working DocBook environment on
2464 Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
2465 with the complete <literal>Doc</literal> category. If you are using
2466 <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
2467 have to help <command>configure</command> a little bit: Set the
2468 environment variables <envar>XmllintCmd</envar> and
2469 <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
2470 <command>xmllint</command> and <command>xsltproc</command>,
2471 respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
2472 of the directory where the XSL stylesheets are installed,
2473 e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
2476 <para>If you want to build HTML Help, you have to install the
2477 <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
2478 too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
2484 <title>Configuring the DocBook tools</title>
2486 <para>Once the DocBook tools are installed, the configure script
2487 will detect them and set up the build system accordingly. If you
2488 have a system that isn't supported, let us know, and we'll try
2493 <title>Building the documentation</title>
2495 <para>To build documentation in a certain format, you can
2496 say, for example,</para>
2498 <screen>$ make html</screen>
2500 <para>to build HTML documentation below the current directory.
2501 The available formats are: <literal>dvi</literal>,
2502 <literal>ps</literal>, <literal>pdf</literal>,
2503 <literal>html</literal>, and <literal>rtf</literal>. Note that
2504 not all documentation can be built in all of these formats: HTML
2505 documentation is generally supported everywhere, and DocBook
2506 documentation might support the other formats (depending on what
2507 other tools you have installed).</para>
2509 <para>All of these targets are recursive; that is, saying
2510 <literal>make html</literal> will make HTML docs for all the
2511 documents recursively below the current directory.</para>
2513 <para>Because there are many different formats that the DocBook
2514 documentation can be generated in, you have to select which ones
2515 you want by setting the <literal>XMLDocWays</literal> variable
2516 to a list of them. For example, in
2517 <filename>build.mk</filename> you might have a line:</para>
2519 <screen>XMLDocWays = html ps</screen>
2521 <para>This will cause the documentation to be built in the requested
2522 formats as part of the main build (the default is not to build
2523 any documentation at all).</para>
2527 <title>Installing the documentation</title>
2529 <para>To install the documentation, use:</para>
2531 <screen>$ make install-docs</screen>
2533 <para>This will install the documentation into
2534 <literal>$(datadir)</literal> (which defaults to
2535 <literal>$(prefix)/share</literal>). The exception is HTML
2536 documentation, which goes into
2537 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
2539 <para>Note that unless you set <literal>$(XMLDocWays)</literal>
2540 to a list of formats, the <literal>install-docs</literal> target
2541 won't do anything for DocBook XML documentation.</para>
2547 <sect1 id="sec-porting-ghc">
2548 <title>Porting GHC</title>
2550 <para>This section describes how to port GHC to a currenly
2551 unsupported platform. There are two distinct
2552 possibilities:</para>
2556 <para>The hardware architecture for your system is already
2557 supported by GHC, but you're running an OS that isn't
2558 supported (or perhaps has been supported in the past, but
2559 currently isn't). This is the easiest type of porting job,
2560 but it still requires some careful bootstrapping. Proceed to
2561 <xref linkend="sec-booting-from-hc"/>.</para>
2565 <para>Your system's hardware architecture isn't supported by
2566 GHC. This will be a more difficult port (though by comparison
2567 perhaps not as difficult as porting gcc). Proceed to <xref
2568 linkend="unregisterised-porting"/>.</para>
2572 <sect2 id="sec-booting-from-hc">
2573 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
2575 <indexterm><primary>building GHC from .hc files</primary></indexterm>
2576 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
2577 <indexterm><primary>porting GHC</primary></indexterm>
2579 <para>Bootstrapping GHC on a system without GHC already
2580 installed is achieved by taking the intermediate C files (known
2581 as HC files) from another GHC compilation, compiling them using gcc to
2582 get a working GHC.</para>
2584 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
2585 from C. We recommend using GHC 6.0.1 or
2586 later.</emphasis></para>
2588 <para>HC files are platform-dependent, so you have to get a set
2589 that were generated on <emphasis>the same platform</emphasis>. There
2590 may be some supplied on the GHC download page, otherwise you'll have to
2591 compile some up yourself, or start from
2592 <emphasis>unregisterised</emphasis> HC files - see <xref
2593 linkend="unregisterised-porting"/>.</para>
2595 <para>The following steps should result in a working GHC build
2596 with full libraries:</para>
2600 <para>Unpack the HC files on top of a fresh source tree
2601 (make sure the source tree version matches the version of
2602 the HC files <emphasis>exactly</emphasis>!). This will
2603 place matching <filename>.hc</filename> files next to the
2604 corresponding Haskell source (<filename>.hs</filename> or
2605 <filename>.lhs</filename>) in the compiler subdirectory
2606 <filename>ghc/compiler</filename> and in the libraries
2608 <literal>libraries</literal>).</para>
2612 <para>The actual build process is fully automated by the
2613 <filename>hc-build</filename> script located in the
2614 <filename>distrib</filename> directory. If you eventually
2615 want to install GHC into the directory
2616 <replaceable>dir</replaceable>, the following
2617 command will execute the whole build process (it won't
2618 install yet):</para>
2620 <screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
2621 <indexterm><primary>--hc-build</primary></indexterm>
2623 <para>By default, the installation directory is
2624 <filename>/usr/local</filename>. If that is what you want,
2625 you may omit the argument to <filename>hc-build</filename>.
2626 Generally, any option given to <filename>hc-build</filename>
2627 is passed through to the configuration script
2628 <filename>configure</filename>. If
2629 <filename>hc-build</filename> successfully completes the
2630 build process, you can install the resulting system, as
2633 <screen>$ make install</screen>
2638 <sect2 id="unregisterised-porting">
2639 <title>Porting GHC to a new architecture</title>
2641 <para>The first step in porting to a new architecture is to get
2642 an <firstterm>unregisterised</firstterm> build working. An
2643 unregisterised build is one that compiles via vanilla C only.
2644 By contrast, a registerised build uses the following
2645 architecture-specific hacks for speed:</para>
2649 <para>Global register variables: certain abstract machine
2650 <quote>registers</quote> are mapped to real machine
2651 registers, depending on how many machine registers are
2653 <filename>ghc/includes/MachRegs.h</filename>).</para>
2657 <para>Assembly-mangling: when compiling via C, we feed the
2658 assembly generated by gcc though a Perl script known as the
2659 <firstterm>mangler</firstterm> (see
2660 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
2661 mangler rearranges the assembly to support tail-calls and
2662 various other optimisations.</para>
2666 <para>In an unregisterised build, neither of these hacks are
2667 used — the idea is that the C code generated by the
2668 compiler should compile using gcc only. The lack of these
2669 optimisations costs about a factor of two in performance, but
2670 since unregisterised compilation is usually just a step on the
2671 way to a full registerised port, we don't mind too much.</para>
2673 <para>Notes on GHC portability in general: we've tried to stick
2674 to writing portable code in most parts of the system, so it
2675 should compile on any POSIXish system with gcc, but in our
2676 experience most systems differ from the standards in one way or
2677 another. Deal with any problems as they arise - if you get
2678 stuck, ask the experts on
2679 <email>glasgow-haskell-users@haskell.org</email>.</para>
2681 <para>Lots of useful information about the innards of GHC is
2682 available in the <ulink
2683 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
2684 Commentary</ulink>, which might be helpful if you run into some
2685 code which needs tweaking for your system.</para>
2688 <title>Cross-compiling to produce an unregisterised GHC</title>
2690 <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
2691 later. If you need instructions for an earlier version of GHC, try
2692 to get hold of the version of this document that was current at the
2693 time. It should be available from the appropriate download page on
2695 url="http://www.haskell.org/ghc/">GHC homepage</ulink>.</para>
2697 <para>In this section, we explain how to bootstrap GHC on a
2698 new platform, using unregisterised intermediate C files. We
2699 haven't put a great deal of effort into automating this
2700 process, for two reasons: it is done very rarely, and the
2701 process usually requires human intervention to cope with minor
2702 porting issues anyway.</para>
2704 <para>The following step-by-step instructions should result in
2705 a fully working, albeit unregisterised, GHC. Firstly, you
2706 need a machine that already has a working GHC (we'll call this
2707 the <firstterm>host</firstterm> machine), in order to
2708 cross-compile the intermediate C files that we will use to
2709 bootstrap the compiler on the <firstterm>target</firstterm>
2714 <para>On the target machine:</para>
2718 <para>Unpack a source tree (preferably a released
2719 version). We will call the path to the root of this
2720 tree <replaceable>T</replaceable>.</para>
2724 <screen>$ cd <replaceable>T</replaceable>
2725 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
2727 <para>You might need to update
2728 <filename>configure.in</filename> to recognise the new
2729 architecture, and re-generate
2730 <filename>configure</filename> with
2731 <literal>autoreconf</literal>.</para>
2735 <screen>$ cd <replaceable>T</replaceable>/ghc/includes
2742 <para>On the host machine:</para>
2746 <para>Unpack a source tree (same released version). Call
2747 this directory <replaceable>H</replaceable>.</para>
2751 <screen>$ cd <replaceable>H</replaceable>
2752 $ ./configure</screen>
2757 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
2758 with the following contents:</para>
2760 <programlisting>GhcUnregisterised = YES
2761 GhcLibHcOpts = -O -fvia-C -keep-hc-files
2762 GhcRtsHcOpts = -keep-hc-files
2765 GhcWithNativeCodeGen = NO
2766 GhcWithInterpreter = NO
2767 GhcStage1HcOpts = -O
2768 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
2769 SRC_HC_OPTS += -H32m
2770 GhcBootLibs = YES</programlisting>
2775 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
2778 <para>change <literal>TARGETPLATFORM</literal>
2779 appropriately, and set the variables involving
2780 <literal>TARGET</literal> to the correct values for
2781 the target platform. This step is necessary because
2782 currently <literal>configure</literal> doesn't cope
2783 with specifying different values for the
2784 <literal>--host</literal> and
2785 <literal>--target</literal> flags.</para>
2788 <para>copy <literal>LeadingUnderscore</literal>
2789 setting from target.</para>
2796 <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>
2798 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
2799 Note that we are building on the host machine, using the
2800 target machine's configuration files. This
2801 is so that the intermediate C files generated here will
2802 be suitable for compiling on the target system.</para>
2806 <para>Touch the generated configuration files, just to make
2807 sure they don't get replaced during the build:</para>
2808 <screen>$ cd <filename><replaceable>H</replaceable></filename>/ghc/includes
2809 $ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
2810 $ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
2812 <para>Note: it has been reported that these files still get
2813 overwritten during the next stage. We have installed a fix
2814 for this in GHC 6.4.2, but if you are building a version
2815 before that you need to watch out for these files getting
2816 overwritte by the <literal>Makefile</literal> in
2817 <literal>ghc/includes</literal>. If your system supports
2818 it, you might be able to prevent it by making them
2820 <screen>$ chflags uchg ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h}</screen>
2824 <para>Now build the compiler:</para>
2825 <screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
2826 $ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
2827 <para>Don't worry if the build falls over in the RTS, we
2828 don't need the RTS yet.</para>
2832 <screen>$ cd <replaceable>H</replaceable>/libraries
2833 $ make boot && make</screen>
2837 <screen>$ cd <replaceable>H</replaceable>/ghc/compiler
2838 $ make boot stage=2 && make stage=2</screen>
2842 <screen>$ cd <replaceable>H</replaceable>/ghc/lib/compat
2845 $ make boot UseStage1=YES
2846 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
2847 $ cd <replaceable>H</replaceable>/ghc/utils
2849 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
2853 <screen>$ cd <replaceable>H</replaceable>
2854 $ make hc-file-bundle Project=Ghc</screen>
2859 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
2860 to <filename><replaceable>T</replaceable>/..</filename>.</para>
2866 <para>On the target machine:</para>
2868 <para>At this stage we simply need to bootstrap a compiler
2869 from the intermediate C files we generated above. The
2870 process of bootstrapping from C files is automated by the
2871 script in <literal>distrib/hc-build</literal>, and is
2872 described in <xref linkend="sec-booting-from-hc"/>.</para>
2874 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
2876 <para>However, since this is a bootstrap on a new machine,
2877 the automated process might not run to completion the
2878 first time. For that reason, you might want to treat the
2879 <literal>hc-build</literal> script as a list of
2880 instructions to follow, rather than as a fully automated
2881 script. This way you'll be able to restart the process
2882 part-way through if you need to fix anything on the
2885 <para>Don't bother with running
2886 <literal>make install</literal> in the newly
2887 bootstrapped tree; just use the compiler in that tree to
2888 build a fresh compiler from scratch, this time without
2889 booting from C files. Before doing this, you might want
2890 to check that the bootstrapped compiler is generating
2891 working binaries:</para>
2893 <screen>$ cat >hello.hs
2894 main = putStrLn "Hello World!\n"
2896 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
2898 Hello World!</screen>
2900 <para>Once you have the unregisterised compiler up and
2901 running, you can use it to start a registerised port. The
2902 following sections describe the various parts of the
2903 system that will need architecture-specific tweaks in
2904 order to get a registerised build going.</para>
2911 <title>Porting the RTS</title>
2913 <para>The following files need architecture-specific code for a
2914 registerised build:</para>
2918 <term><filename>ghc/includes/MachRegs.h</filename>
2919 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
2922 <para>Defines the STG-register to machine-register
2923 mapping. You need to know your platform's C calling
2924 convention, and which registers are generally available
2925 for mapping to global register variables. There are
2926 plenty of useful comments in this file.</para>
2930 <term><filename>ghc/includes/TailCalls.h</filename>
2931 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
2934 <para>Macros that cooperate with the mangler (see <xref
2935 linkend="sec-mangler"/>) to make proper tail-calls
2940 <term><filename>ghc/rts/Adjustor.c</filename>
2941 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
2945 <literal>foreign import "wrapper"</literal>
2947 <literal>foreign export dynamic</literal>).
2948 Not essential for getting GHC bootstrapped, so this file
2949 can be deferred until later if necessary.</para>
2953 <term><filename>ghc/rts/StgCRun.c</filename>
2954 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
2957 <para>The little assembly layer between the C world and
2958 the Haskell world. See the comments and code for the
2959 other architectures in this file for pointers.</para>
2963 <term><filename>ghc/rts/MBlock.h</filename>
2964 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
2966 <term><filename>ghc/rts/MBlock.c</filename>
2967 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
2970 <para>These files are really OS-specific rather than
2971 architecture-specific. In <filename>MBlock.h</filename>
2972 is specified the absolute location at which the RTS
2973 should try to allocate memory on your platform (try to
2974 find an area which doesn't conflict with code or dynamic
2975 libraries). In <filename>Mblock.c</filename> you might
2976 need to tweak the call to <literal>mmap()</literal> for
2983 <sect3 id="sec-mangler">
2984 <title>The mangler</title>
2986 <para>The mangler is an evil Perl-script
2987 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
2988 rearranges the assembly code output from gcc to do two main
2993 <para>Remove function prologues and epilogues, and all
2994 movement of the C stack pointer. This is to support
2995 tail-calls: every code block in Haskell code ends in an
2996 explicit jump, so we don't want the C-stack overflowing
2997 while we're jumping around between code blocks.</para>
3000 <para>Move the <firstterm>info table</firstterm> for a
3001 closure next to the entry code for that closure. In
3002 unregisterised code, info tables contain a pointer to the
3003 entry code, but in registerised compilation we arrange
3004 that the info table is shoved right up against the entry
3005 code, and addressed backwards from the entry code pointer
3006 (this saves a word in the info table and an extra
3007 indirection when jumping to the closure entry
3012 <para>The mangler is abstracted to a certain extent over some
3013 architecture-specific things such as the particular assembler
3014 directives used to herald symbols. Take a look at the
3015 definitions for other architectures and use these as a
3016 starting point.</para>
3020 <title>The splitter</title>
3022 <para>The splitter is another evil Perl script
3023 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
3024 cooperates with the mangler to support object splitting.
3025 Object splitting is what happens when the
3026 <option>-split-objs</option> option is passed to GHC: the
3027 object file is split into many smaller objects. This feature
3028 is used when building libraries, so that a program statically
3029 linked against the library will pull in less of the
3032 <para>The splitter has some platform-specific stuff; take a
3033 look and tweak it for your system.</para>
3037 <title>The native code generator</title>
3039 <para>The native code generator isn't essential to getting a
3040 registerised build going, but it's a desirable thing to have
3041 because it can cut compilation times in half. The native code
3042 generator is described in some detail in the <ulink
3043 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3044 commentary</ulink>.</para>
3050 <para>To support GHCi, you need to port the dynamic linker
3051 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
3052 currently supports the ELF and PEi386 object file formats - if
3053 your platform uses one of these then things will be
3054 significantly easier. The majority of Unix platforms use the
3055 ELF format these days. Even so, there are some
3056 machine-specific parts of the ELF linker: for example, the
3057 code for resolving particular relocation types is
3058 machine-specific, so some porting of this code to your
3059 architecture will probaly be necessary.</para>
3061 <para>If your system uses a different object file format, then
3062 you have to write a linker — good luck!</para>
3068 <sect1 id="sec-build-pitfalls">
3069 <title>Known pitfalls in building Glasgow Haskell
3071 <indexterm><primary>problems, building</primary></indexterm>
3072 <indexterm><primary>pitfalls, in building</primary></indexterm>
3073 <indexterm><primary>building pitfalls</primary></indexterm></title>
3076 WARNINGS about pitfalls and known “problems”:
3085 One difficulty that comes up from time to time is running out of space
3086 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
3087 compensate for the vagaries of different sysadmin approaches to temp
3089 <indexterm><primary>tmp, running out of space in</primary></indexterm>
3091 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
3092 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
3095 The best way around it is to say
3097 <programlisting>export TMPDIR=<dir></programlisting>
3099 in your <filename>build.mk</filename> file.
3100 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
3109 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
3110 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
3118 When compiling via C, you'll sometimes get “warning: assignment from
3119 incompatible pointer type” out of GCC. Harmless.
3126 Similarly, <command>ar</command>chiving warning messages like the following are not
3129 <screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
3130 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
3139 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
3140 get an “Out of heap space” error message. These can vary with the
3141 vagaries of different systems, it seems. The solution is simple:
3148 If you're compiling with GHC 4.00 or later, then the
3149 <emphasis>maximum</emphasis> heap size must have been reached. This
3150 is somewhat unlikely, since the maximum is set to 64M by default.
3151 Anyway, you can raise it with the
3152 <option>-optCrts-M<size></option> flag (add this flag to
3153 <constant><module>_HC_OPTS</constant>
3154 <command>make</command> variable in the appropriate
3155 <filename>Makefile</filename>).
3162 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
3171 and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
3172 <constant><module>_HC_OPTS</constant>.)
3174 Alternatively, just cut to the chase:
3176 <screen>$ cd ghc/compiler
3177 $ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
3185 If you try to compile some Haskell, and you get errors from GCC about
3186 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
3187 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
3189 As <command>fixincludes</command> is now automagically run as part of GCC installation,
3190 this bug also suggests that you have an old GCC.
3198 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
3201 <screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
3202 $ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
3204 ? # or, on some machines: ar s $i
3208 We'd be interested to know if this is still necessary.
3216 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
3217 a bit from one Unix to another. One particular gotcha is macro calls
3221 <programlisting>SLIT("Hello, world")</programlisting>
3224 Some <command>cpp</command>s treat the comma inside the string as separating two macro
3225 arguments, so you get
3228 <screen>:731: macro `SLIT' used with too many (2) args</screen>
3231 Alas, <command>cpp</command> doesn't tell you the offending file!
3233 Workaround: don't put weird things in string args to <command>cpp</command> macros.
3244 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
3246 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
3247 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
3250 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
3252 <para> The build system is built around Unix-y makefiles. Because it's not native,
3253 the Windows situation for building GHC is particularly confusing. This section
3254 tries to clarify, and to establish terminology.</para>
3256 <sect3 id="ghc-mingw"><title>MinGW</title>
3258 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
3259 is a collection of header
3260 files and import libraries that allow one to use <command>gcc</command> and produce
3261 native Win32 programs that do not rely on any third-party DLLs. The
3262 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
3263 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
3267 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
3272 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
3274 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
3275 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
3276 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</command>.
3277 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
3278 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
3282 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
3283 compile code that has access to all of Posix. The price is that the executables must be
3284 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
3285 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
3286 does not change, but the implementation certainly does. Even the interfaces to functions
3287 it exports seem to change occasionally. </para>
3291 MSYS is a fork of the Cygwin tree, so they
3292 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
3293 through fewer layers, so MSYS is quite a bit faster too.
3296 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
3297 compile binaries that run with no DLL support, on any Win32 system.
3298 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
3299 <command>darcs</command>, <command>ssh</command> etc. To get these, you have to download the
3300 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
3302 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
3303 <command>ssh</command> and so on),
3304 not by programs compiled under MSYS.
3312 <sect3><title>Targeting MinGW</title>
3314 <para>We want GHC to compile programs that work on any Win32 system. Hence:
3317 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
3318 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
3319 will work on any system, but it also means that the programs GHC compiles do not have access
3320 to all of Posix. In particular, they cannot import the (Haskell) Posix
3321 library; they have to do
3322 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
3323 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
3327 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
3328 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
3331 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
3332 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
3333 that targets Cygwin instead. The up-side of GHC-cygwin is
3334 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
3335 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
3338 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
3339 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
3340 GHC; both work fine, though MSYS is rather lighter weight.</para>
3342 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
3343 uses the <command>gcc</command> that you specify using the
3344 <option>--with-gcc</option> flag when you run
3345 <command>configure</command> (see below).
3346 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
3347 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
3348 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
3349 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
3350 used to glom together .o files into a bigger .o file, or a .a file,
3351 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
3352 Cygwin and MinGW use the same .o file format. So its ok.
3356 <sect3><title> File names </title>
3358 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
3362 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
3363 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
3365 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
3366 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
3367 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
3369 <programlisting>foogle -B/c/tmp/baz</programlisting>
3370 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
3374 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
3376 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
3382 <sect3><title>Crippled <command>ld</command></title>
3385 It turns out that on both Cygwin and MSYS, the <command>ld</command> has a
3386 limit of 32kbytes on its command line. Especially when using split object
3387 files, the make system can emit calls to <command>ld</command> with thousands
3388 of files on it. Then you may see something like this:
3390 (cd Graphics/Rendering/OpenGL/GL/QueryUtils_split && /mingw/bin/ld -r -x -o ../QueryUtils.o *.o)
3391 /bin/sh: /mingw/bin/ld: Invalid argument
3393 The solution is either to switch off object file splitting (set
3394 <option>SplitObjs</option> to <literal>NO</literal> in your
3395 <filename>build.mk</filename>),
3396 or to make the module smaller.
3400 <sect3><title>Host System vs Target System</title>
3403 In the source code you'll find various ifdefs looking like:
3404 <programlisting>#ifdef mingw32_HOST_OS
3406 #endif</programlisting>
3408 <programlisting>#ifdef mingw32_TARGET_OS
3410 #endif</programlisting>
3411 These macros are set by the configure script (via the file config.h).
3412 Which is which? The criterion is this. In the ifdefs in GHC's source code:
3415 <para>The "host" system is the one on which GHC itself will be run.</para>
3418 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
3421 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
3422 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
3429 <sect2><title>Wrapper scripts</title>
3432 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
3433 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
3434 GHC itself as an example:
3437 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
3438 paths to the front of the source file <filename>ghc.sh</filename>,
3439 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
3440 where to find its supporting files.
3444 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
3445 native Windows shell <command>cmd</command> (e.g. limits on the length
3446 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
3447 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
3448 and from that figures out where the supporting files are.
3451 (You can find the layout of GHC's supporting files in the
3452 section "Layout of installed files" of Section 2 of the GHC user guide.)
3455 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
3456 execute a program that has just been built in a build tree. The difference is that the
3457 layout of the supporting files is different.
3458 In this case, whether on Windows or Unix, we always use a shell script. This works OK
3459 on Windows because the script is executed by MSYS or Cygwin, which don't have the
3460 shortcomings of the native Windows <command>cmd</command> shell.
3467 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
3470 This section gives detailed instructions for how to build
3471 GHC from source on your Windows machine. Similar instructions for
3472 installing and running GHC may be found in the user guide. In general,
3473 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
3476 Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
3477 before reading section.
3478 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
3479 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
3482 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
3485 MSYS is a lightweight alternative to Cygwin.
3486 You don't need MSYS to <emphasis>use</emphasis> GHC,
3487 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
3488 Here's how to install MSYS.
3491 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
3492 download the following (of course, the version numbers will differ):
3494 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
3496 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
3497 This provides <command>make</command>, <command>autoconf</command>,
3498 <command>ssh</command> and probably more besides.
3501 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
3505 Set the following environment variables
3507 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> and
3508 <literal>c:/msys/1.0/local/bin</literal>
3509 to your path. (Of course, the version number may differ.)
3510 MSYS mounts the former as both <literal>/bin</literal> and
3511 <literal>/usr/bin</literal> and the latter as <literal>/usr/local/bin</literal>.
3514 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
3515 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
3518 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
3521 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
3525 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
3532 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
3533 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
3534 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
3535 file has too-liberal permissinos.
3540 <para>Here are some points to bear in mind when using MSYS:
3542 <listitem> <para> MSYS does some kind of special magic to binaries stored in
3543 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
3544 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
3545 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
3546 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
3547 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
3549 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
3553 Win32 has a <command>find</command> command which is not the same as MSYS's find.
3554 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
3555 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
3556 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
3557 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
3561 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
3562 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
3563 bzip'd dump.</para></listitem>
3569 <sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title>
3571 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
3572 The installation process is straightforward; we install it in
3573 <filename>c:/cygwin</filename>.</para>
3575 You must install enough Cygwin <emphasis>packages</emphasis> to support
3576 building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this:
3578 <listitem><para>The direct, but laborious way is to
3579 select all of the following packages in the installation dialogue:
3580 <command>cvs</command>,
3581 <command>openssh</command>,
3582 <command>autoconf</command>,
3583 <command>binutils</command> (includes ld and (I think) ar),
3584 <command>gcc</command>,
3585 <command>flex</command>,
3586 <command>make</command>.
3587 To see thse packages,
3588 click on the "View" button in the "Select Packages"
3589 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
3590 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
3594 <listitem><para>The clever way is to point the Cygwin installer at the
3595 <command>ghc-depends</command> package, which is kept at <ulink
3596 url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
3597 When the Cygwin installer asks you to "Choose a Download Site", choose one of
3599 offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
3600 "User URL" box and click "Add"; now two sites are selected. (The Cygwin
3601 installer remembers this for next time.)
3602 Click "Next".</para>
3603 <para>In the "Select Packages" dialogue box that follows, click the "+" sign by
3604 "Devel", scroll down to the end of the "Devel" packages, and choose
3605 <command>ghc-depends</command>.
3606 The package <command>ghc-depends</command> will not actually install anything itself,
3607 but forces additional packages to be added by the Cygwin installer.
3613 <para> Now set the following user environment variables:
3616 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
3617 <constant>PATH</constant></para></listitem>
3621 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
3622 don't do this you get very weird messages when you type
3623 <command>make</command>, such as:
3624 <screen>/c: /c: No such file or directory</screen>
3628 <listitem><para> Set <constant>SHELL</constant> to
3629 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
3630 <constant>SHELL</constant> is what you get.
3633 <listitem><para> Set <constant>HOME</constant> to point to your
3634 home directory. This is where, for example,
3635 <command>bash</command> will look for your <filename>.bashrc</filename>
3636 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
3641 <para>Here are some things to be aware of when using Cygwin:
3643 <listitem> <para>Cygwin doesn't deal well with filenames that include
3644 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
3648 <listitem> <para> Cygwin implements a symbolic link as a text file with some
3649 magical text in it. So other programs that don't use Cygwin's
3650 I/O libraries won't recognise such files as symlinks.
3651 In particular, programs compiled by GHC are meant to be runnable
3652 without having Cygwin, so they don't use the Cygwin library, so
3653 they don't recognise symlinks.
3657 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
3658 which apply to Cygwin too.
3663 Some script files used in the make system start with "<command>#!/bin/perl</command>",
3664 (and similarly for <command>sh</command>). Notice the hardwired path!
3665 So you need to ensure that your <filename>/bin</filename> directory has at least
3666 <command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
3667 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
3668 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
3669 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
3670 (You can discover where your Cygwin
3671 root directory <filename>/</filename> is by typing <command>mount</command>.)
3672 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
3673 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
3674 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
3680 By default, cygwin provides the command shell <filename>ash</filename>
3681 as <filename>sh.exe</filename>. It seems to be fine now, but in the past we
3682 saw build-system problems that turned out to be due to bugs in <filename>ash</filename>
3683 (to do with quoting and length of command lines). On the other hand <filename>bash</filename> seems
3685 If this happens to you (which it shouldn't), in <filename>cygwin/bin</filename>
3686 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
3687 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
3688 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
3689 you can't rename a running program!
3698 <sect2 id="configure-ssh"><title>Configuring SSH</title>
3700 <para><command>ssh</command> comes with both Cygwin and MSYS.
3701 (Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
3702 in the Cygwin list of packages; or use the <command>ghc-depends</command>
3703 package -- see <xref linkend="install-cygwin"/>.)</para>
3705 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
3709 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
3710 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
3711 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
3712 and run it as follows:
3713 <screen>c:\tmp> set CYGWIN32=tty
3714 c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
3717 <listitem><para> (Cygwin-only problem, I think.)
3718 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
3719 To determine your home directory <command>ssh</command> first looks in
3720 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
3721 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
3722 the setting of the environment variable $HOME</emphasis>. If the home directory is
3723 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
3724 <screen>ssh -v cvs.haskell.org</screen>
3725 which makes <command>ssh</command> print out information about its activity.
3727 <para> You can fix this problem, either by correcting the home-directory field in
3728 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
3729 you do that, <command>ssh</command> uses the $HOME environment variable instead.
3735 <para>To protect your
3736 <literal>.ssh</literal> from access by anyone else,
3737 right-click your <literal>.ssh</literal> directory, and
3738 select <literal>Properties</literal>. If you are not on
3739 the access control list, add yourself, and give yourself
3740 full permissions (the second panel). Remove everyone else
3741 from the access control list. Don't leave them there but
3742 deny them access, because 'they' may be a list that
3743 includes you!</para>
3747 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
3748 you to have Unix permissions 600 (read/write for owner only)
3749 on the <literal>.ssh/identity</literal> file, else it
3750 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
3751 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
3752 The solution seems to be to set the $CYGWIN environment
3753 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
3754 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
3755 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
3762 <sect2><title>Other things you need to install</title>
3764 <para>You have to install the following other things to build GHC, listed below.</para>
3766 <para>On Windows you often install executables in directories with spaces, such as
3767 "<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
3768 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
3769 to put binaries for all tools in places with no spaces in their path.
3770 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
3771 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
3772 provided they are in your path.
3776 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
3777 This is what you will use to compile GHC. Add it in your
3778 <constant>PATH</constant>: the installer tells you the path element
3779 you need to add upon completion.
3785 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
3786 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
3787 build it from the source distribution using
3788 <screen>$ ./configure
3790 $ make install</screen>
3791 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
3793 Make sure the installation directory is in your
3794 <constant>PATH</constant>.
3799 <para>Install an executable Alex. This can be done by building from the
3800 source distribution in the same way as Happy. Sources are
3801 available from <ulink
3802 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
3806 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
3807 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
3808 Just pick up a mingw bundle at
3809 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
3810 We install it in <filename>c:/mingw</filename>.
3813 <para><emphasis>On MSYS</emphasis>, add <literal>c:/mingw/bin</literal> to your PATH. MSYS does not provide <command>gcc</command>,
3814 <command>ld</command>, <command>ar</command>, and so on, because it just uses the MinGW ones. So you need them
3818 <para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
3819 They are only going to get used by explicit access (via the --with-gcc flag you
3820 give to <command>configure</command> later). If you do add them to your path
3821 you are likely to get into a mess because their names overlap with Cygwin
3823 On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
3824 (and perhaps one or two other things) in your path. The Cygwin ones are fine,
3825 but you must have them; hence needing the Cygwin binutils package.
3831 <para>We use <command>emacs</command> a lot, so we install that too.
3832 When you are in <filename>fptools/ghc/compiler</filename>, you can use
3833 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
3834 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
3835 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
3836 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
3837 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
3842 <para>You might want to install GLUT in your MSYS/Cygwin
3843 installation, otherwise the GLUT package will not be built with
3848 <para> Finally, check out a copy of GHC sources from
3849 the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para>
3855 <sect2><title>Building GHC</title>
3858 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
3859 the bullets below only tell
3860 you about Windows-specific wrinkles.</para>
3864 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
3865 you'll get an error when you run <filename>./configure</filename>:
3868 creating mk/config.h
3869 mk/config.h is unchanged
3871 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
3872 ./configure: ./configure: No such file or directory
3873 configure: error: ./configure failed for ghc</screen>
3877 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
3878 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
3880 <screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
3881 Solution: delete <filename>configure</filename> first.
3886 After <command>autoreconf</command> run <command>./configure</command> in
3887 <filename>fptools/</filename> thus:
3889 <screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
3890 This is the point at which you specify that you are building GHC-mingw
3891 (see <xref linkend="ghc-mingw"/>). </para>
3893 <para> Both these options are important! It's possible to get into
3894 trouble using the wrong C compiler!</para>
3896 Furthermore, it's <emphasis>very important</emphasis> that you specify a
3897 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
3898 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
3899 understand a Cygwin path. For example, if you
3900 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
3901 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
3902 time it tries to invoke it. Worse, the failure comes with
3903 no error message whatsoever. GHC simply fails silently when first invoked,
3904 typically leaving you with this:
3905 <screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
3906 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
3907 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
3908 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
3909 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
3910 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
3911 -optc-fomit-frame-pointer -O2 -static
3912 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
3913 make[2]: *** [Adjustor.o] Error 1
3914 make[1]: *** [all] Error 1
3915 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
3916 make: *** [all] Error 1</screen>
3921 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
3922 you'll have to do something more like:
3923 <screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
3928 If you are paranoid, delete <filename>config.cache</filename> if it exists.
3929 This file occasionally remembers out-of-date configuration information, which
3930 can be really confusing.
3934 <listitem><para> You almost certainly want to set
3935 <programlisting>SplitObjs = NO</programlisting>
3936 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
3937 This tells the build system not to split each library into a myriad of little object files, one
3938 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
3939 it dramatically increases the time taken to build the libraries in the first place.
3943 <listitem><para> Do not attempt to build the documentation.
3944 It needs all kinds of wierd Jade stuff that we haven't worked out for
3945 Win32.</para></listitem>
3950 <sect2><title>A Windows build log using Cygwin</title>
3952 <para>Here is a complete, from-scratch, log of all you need to build GHC using
3953 Cygwin, kindly provided by Claus Reinke. It does not discuss alternative
3954 choices, but it gives a single path that works.</para>
3955 <programlisting>- Install some editor (vim, emacs, whatever)
3957 - Install cygwin (http://www.cygwin.com)
3958 ; i used 1.5.16-1, installed in c:\cygwin
3960 Choose a Download Source:
3961 select 'download from internet';
3962 Select Root Install Directory:
3963 root dir: c:\cygwin;
3964 install for: all users;
3965 default file type: unix
3966 Select Local Package Directory
3967 choose a spare temporary home
3968 Select Your Internet Connection
3970 Choose a Download Site
3971 Choose your preferred main mirror and
3972 Add 'http://www.haskell.org/ghc/cygwin'
3974 In addition to 'Base' (default install),
3975 select 'Devel->ghc-depends'
3977 - Install mingw (http://www.mingw.org/)
3978 ; i used MinGW-3.1.0-1.exe
3979 ; installed in c:\mingw
3980 - you probably want to add GLUT
3981 ; (http://www.xmission.com/~nate/glut.html)
3982 ; i used glut-3.7.3-mingw32.tar
3984 - Get recent binary snapshot of ghc-6.4.1 for mingw
3985 ; (http://www.haskell.org/ghc/dist/stable/dist/)
3987 - add C:\ghc\ghc-6.4.1\bin to %PATH%
3988 (Start->Control Panel->System->Advanced->Environment Variables)
3990 - Get darcs version of ghc
3991 ; also, subscribe to cvs-all@haskell.org, or follow the mailing list
3992 ; archive, in case you checkout a version with problems
3993 ; http://www.haskell.org//pipermail/cvs-all/
3994 - mkdir c:/fptools; cd c:/fptools
3995 ; (or whereever you want your darcs tree to be)
3996 - darcs get http://darcs.haskell.org/ghc
3998 - chmod +x darcs-all
4001 - Build ghc, using cygwin and mingw, targetting mingw
4002 - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
4003 ; for haddock, alex, happy (*)
4004 - export PATH=/cygdrive/c/mingw/bin:$PATH
4005 ; without, we pick up some cygwin tools at best!
4006 - cd c:/fptools/fptools
4007 ; (if you aren't there already)
4009 - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
4010 ; we use cygwin, but build for windows
4011 - cp mk/build.mk.sample mk/build.mk
4013 add line: SplitObjs = NO
4014 (MSYS seems slow when there are zillions of object files)
4015 uncomment line: BuildFlavour = perf
4016 (or BuildFlavour = devel, if you are doing development)
4017 add line: BIN_DIST=1
4018 - make 2>&1 | tee make.log
4019 ; always useful to have a log around
4021 - Package up binary distribution
4022 - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log
4023 ; always useful to have a log around
4025 - chmod +x ../distrib/prep-bin-dist-mingw
4026 ; if you're happy with the script's contents (*)
4027 - ../distrib/prep-bin-dist-mingw
4028 ; then tar up, unpack where wanted, and enjoy</programlisting>
projects / ghc-hetmet.git / blob