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. <xref
100 linkend="sec-port-info"/> lists the supported platforms; if
101 yours isn't amongst these then you can try porting GHC (see
102 <xref linkend="sec-porting-ghc"/>).</para>
106 <para>Be sure that the “pre-supposed” utilities are
107 installed. <xref linkend="sec-pre-supposed"/>
112 <para>If you have any problem when building or installing the
113 Glasgow tools, please check the “known pitfalls” (<xref
114 linkend="sec-build-pitfalls"/>). Also check the FAQ for the
115 version you're building, which is part of the User's Guide and
116 available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
119 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
121 <para>If you feel there is still some shortcoming in our
122 procedure or instructions, please report it.</para>
124 <para>For GHC, please see the <ulink
125 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
126 section of the GHC Users' Guide</ulink>, to maximise the
127 usefulness of your report.</para>
129 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
130 <para>If in doubt, please send a message to
131 <email>glasgow-haskell-bugs@haskell.org</email>.
132 <indexterm><primary>bugs</primary><secondary>mailing
133 list</secondary></indexterm></para>
138 <sect1 id="sec-port-info">
139 <title>What machines GHC runs on</title>
141 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
142 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
143 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
145 <para>The main question is whether or not the Haskell compiler
146 (GHC) runs on your platform.</para>
148 <para>A “platform” is a
149 architecture/manufacturer/operating-system combination, such as
150 <literal>sparc-sun-solaris2</literal>. Other common ones are
151 <literal>alpha-dec-osf2</literal>,
152 <literal>hppa1.1-hp-hpux9</literal>,
153 <literal>i386-unknown-linux</literal>,
154 <literal>i386-unknown-solaris2</literal>,
155 <literal>i386-unknown-freebsd</literal>,
156 <literal>i386-unknown-cygwin32</literal>,
157 <literal>m68k-sun-sunos4</literal>,
158 <literal>mips-sgi-irix5</literal>,
159 <literal>sparc-sun-sunos4</literal>,
160 <literal>sparc-sun-solaris2</literal>,
161 <literal>powerpc-ibm-aix</literal>.</para>
163 <para>Some libraries may only work on a limited number of
164 platforms; for example, a sockets library is of no use unless the
165 operating system supports the underlying BSDisms.</para>
168 <title>What platforms the Haskell compiler (GHC) runs on</title>
170 <indexterm><primary>fully-supported platforms</primary></indexterm>
171 <indexterm><primary>native-code generator</primary></indexterm>
172 <indexterm><primary>registerised ports</primary></indexterm>
173 <indexterm><primary>unregisterised ports</primary></indexterm>
175 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
176 native-code generator; (b) next best is a
177 “registerised” port; (c) the bare minimum is an
178 “unregisterised” port.
179 (“Unregisterised” is so terrible that we won't say
180 more about it).</para>
182 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
183 FreeBSD and Linux, so those are the best supported platforms,
184 unsurprisingly.</para>
186 <para>Here's everything that's known about GHC ports. We
187 identify platforms by their “canonical”
188 CPU/Manufacturer/OS triple.</para>
192 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
193 <indexterm><primary>alpha-dec-osf</primary></indexterm>
194 <indexterm><primary>alpha-dec-linux</primary></indexterm>
195 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
196 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
197 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
200 <para>The OSF port is currently working (as of GHC version
201 5.02.1) and well supported. The native code generator is
202 currently non-working. Other operating systems will
203 require some minor porting.</para>
208 <term>sparc-sun-sunos4
209 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
212 <para>Probably works with minor tweaks, hasn't been tested
218 <term>sparc-sun-solaris2
219 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
222 <para>Fully supported (at least for Solaris 2.7 and 2.6),
223 including native-code generator.</para>
228 <term>sparc-unknown-openbsd
229 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
232 <para>Supported, including native-code generator. The
233 same should also be true of NetBSD</para>
238 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
239 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
242 <para>A registerised port is available for version 4.08,
243 but GHC hasn't been built on that platform since (as far
244 as we know). No native-code generator.</para>
249 <term>i386-unknown-linux (PCs running Linux, ELF binary format)
250 <indexterm><primary>i386-*-linux</primary></indexterm>
253 <para>GHC works registerised and has a native code
254 generator. You <emphasis>must</emphasis> have GCC 2.7.x
255 or later. NOTE about <literal>glibc</literal> versions:
256 GHC binaries built on a system running <literal>glibc
257 2.0</literal> won't work on a system running
258 <literal>glibc 2.1</literal>, and vice versa. In general,
259 don't expect compatibility between
260 <literal>glibc</literal> versions, even if the shared
261 library version hasn't changed.</para>
266 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
267 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
270 <para>GHC works registerised. Pre-built packages are
271 available in the native package format, so if you just
272 need binaries you're better off just installing the
273 package (it might even be on your installation
279 <term>i386-unknown-openbsd (PCs running OpenBSD)
280 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
283 <para>Supported, with native code generator. Packages are
284 available through the ports system in the native package
290 <term>i386-unknown-netbsd (PCs running NetBSD)
291 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
294 <para>Will require some minor porting effort, but should
295 work registerised.</para>
300 <term>i386-unknown-mingw32 (PCs running Windows)
301 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
304 <para>Fully supported under Win9x, WinNT, Win2k, and
305 WinXP. Includes a native code generator. Building from
306 source requires a recent <ulink
307 url="http://www.cygwin.com/">Cygwin</ulink> distribution
308 to be installed.</para>
313 <term>ia64-unknown-linux
314 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
317 <para>Supported, except there is no native code
323 <term>x86_64-unknown-linux
324 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
326 <term>amd64-unknown-openbsd
327 <indexterm><primary>amd64-unknown-linux</primary></indexterm>
330 <para>Fully supported, with a native code generator and GHCi.</para>
336 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
339 <para>Port has worked in the past, but hasn't been tested
340 for some time (and will certainly have rotted in various
341 ways). As usual, we don't have access to machines and
342 there hasn't been an overwhelming demand for this port,
343 but feel free to get in touch.</para>
348 <term>mips64-sgi-irix6
349 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
352 <para>GHC currently works unregisterised.</para>
357 <term>powerpc-ibm-aix
358 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
361 <para>Port currently doesn't work, needs some minimal
362 porting effort. As usual, we don't have access to
363 machines and there hasn't been an overwhelming demand for
364 this port, but feel free to get in touch.</para>
369 <term>powerpc-apple-darwin
370 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
373 <para>Supported registerised. Native code generator is
374 almost working.</para>
379 <term>powerpc-apple-linux
380 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
383 <para>Not supported (yet).</para>
388 <para>Various other systems have had GHC ported to them in the
389 distant past, including various Motorola 68k boxes. The 68k
390 support still remains, but porting to one of these systems will
391 certainly be a non-trivial task.</para>
395 <sect1 id="sec-pre-supposed">
396 <title>Installing pre-supposed utilities</title>
398 <indexterm><primary>pre-supposed utilities</primary></indexterm>
399 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
401 <para>Here are the gory details about some utility programs you
402 may need; <command>perl</command>, <command>gcc</command> and
403 <command>happy</command> are the only important
404 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
405 important if you're going for Parallel Haskell.) The
406 <command>configure</command><indexterm><primary>configure</primary></indexterm>
407 script will tell you if you are missing something.</para>
413 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
414 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
417 <para>GHC is required to build many of the tools, including
418 GHC itself. If you need to port GHC to your platform
419 because there isn't a binary distribution of GHC available,
420 then see <xref linkend="sec-porting-ghc"/>.</para>
422 <para>Which version of GHC you need will depend on the
423 packages you intend to build. GHC itself will normally
424 build using one of several older versions of itself - check
425 the announcement or release notes for details.</para>
431 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
432 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
435 <para><emphasis>You have to have Perl to proceed!</emphasis>
436 Perl version 5 at least is required. GHC has been known to
437 tickle bugs in Perl, so if you find that Perl crashes when
438 running GHC try updating (or downgrading) your Perl
439 installation. Versions of Perl before 5.6 have been known to have
440 various bugs tickled by GHC, so the configure script
441 will look for version 5.6 or later.</para>
443 <para>For Win32 platforms, you should use the binary
444 supplied in the InstallShield (copy it to
445 <filename>/bin</filename>). The Cygwin-supplied Perl seems
448 <para>Perl should be put somewhere so that it can be invoked
449 by the <literal>#!</literal> script-invoking
450 mechanism. The full pathname may need to be less than 32
451 characters long on some systems.</para>
456 <term>GNU C (<command>gcc</command>)
457 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
458 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
461 <para>Most GCC versions should work with the most recent GHC
462 sources. Expect trouble if you use a recent GCC with
463 an older GHC, though (trouble in the form of mis-compiled code,
464 link errors, and errors from the <literal>ghc-asm</literal>
467 <para>If your GCC dies with “internal error” on
468 some GHC source file, please let us know, so we can report
469 it and get things improved. (Exception: on x86
470 boxes—you may need to fiddle with GHC's
471 <option>-monly-N-regs</option> option; see the User's
478 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
481 <para>The fptools build system makes heavy use of features
482 specific to GNU <command>make</command>, so you must have
483 this installed in order to build any of the fptools
486 <para>NB. it has been reported that version 3.79 no longer
487 works to build GHC, and 3.80 is required.</para>
492 <term><ulink url="http://www.haskell.org/happy">Happy</ulink>
493 <indexterm><primary>Happy</primary></indexterm>
496 <para>Happy is a parser generator tool for Haskell, and is
497 used to generate GHC's parsers.</para>
499 <para>If you start from a source tarball of GHC (i.e. not a darcs
500 checkout), then you don't need Happy, because we supply the
501 pre-processed versions of the Happy parsers. If you intend to
502 modify the compiler and/or you're using a darcs checkout, then you
505 <para>Happy version 1.15 is currently required to build GHC.</para>
507 <para>Happy is written in
508 Haskell, and is a project in the CVS repository
509 (<literal>fptools/happy</literal>). It can be built from
510 source, but bear in mind that you'll need GHC installed in
511 order to build it. To avoid the chicken/egg problem,
512 install a binary distribution of either Happy or GHC to get
513 started. Happy distributions are available from <ulink url="http://www.haskell.org/happy/">Happy's Web
520 <indexterm><primary>Alex</primary></indexterm>
523 <para>Alex is a lexical-analyser generator for Haskell,
524 which GHC uses to generate its lexer.</para>
526 <para>Like Happy, you don't need Alex if you're building GHC from a
527 source tarball, but you do need it if you're modifying GHC and/or
528 building a darcs checkout.</para>
531 written in Haskell and is a project in the darcs repository.
532 Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
539 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
540 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
543 <para>GNU autoconf is needed if you intend to build from the
544 darcs sources, it is <emphasis>not</emphasis> needed if you
545 just intend to build a standard source distribution.</para>
547 <para>Version 2.52 or later of the autoconf package is required.
548 NB. version 2.13 will no longer work, as of GHC version
551 <para><command>autoreconf</command> (from the autoconf package)
552 recursively builds <command>configure</command> scripts from
553 the corresponding <filename>configure.ac</filename> and
554 <filename>aclocal.m4</filename> files. If you modify one of
555 the latter files, you'll need <command>autoreconf</command> to
556 rebuild the corresponding <filename>configure</filename>.</para>
561 <term><command>sed</command>
562 <indexterm><primary>pre-supposed: sed</primary></indexterm>
563 <indexterm><primary>sed, pre-supposed</primary></indexterm>
566 <para>You need a working <command>sed</command> if you are
567 going to build from sources. The build-configuration stuff
568 needs it. GNU sed version 2.0.4 is no good! It has a bug
569 in it that is tickled by the build-configuration. 2.0.5 is
570 OK. Others are probably OK too (assuming we don't create too
571 elaborate configure scripts.)</para>
576 <para>One <literal>fptools</literal> project is worth a quick note
577 at this point, because it is useful for all the others:
578 <literal>glafp-utils</literal> contains several utilities which
579 aren't particularly Glasgow-ish, but Occasionally Indispensable.
580 Like <command>lndir</command> for creating symbolic link
583 <sect2 id="pre-supposed-gph-tools">
584 <title>Tools for building parallel GHC (GPH)</title>
589 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
590 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
593 <para>PVM is the Parallel Virtual Machine on which
594 Parallel Haskell programs run. (You only need this if you
595 plan to run Parallel Haskell. Concurrent Haskell, which
596 runs concurrent threads on a uniprocessor doesn't need
597 it.) Underneath PVM, you can have (for example) a network
598 of workstations (slow) or a multiprocessor box
601 <para>The current version of PVM is 3.3.11; we use 3.3.7.
602 It is readily available on the net; I think I got it from
603 <literal>research.att.com</literal>, in
604 <filename>netlib</filename>.</para>
606 <para>A PVM installation is slightly quirky, but easy to
607 do. Just follow the <filename>Readme</filename>
613 <term><command>bash</command>:
614 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
617 <para>Sadly, the <command>gr2ps</command> script, used to
618 convert “parallelism profiles” to PostScript,
619 is written in Bash (GNU's Bourne Again shell). This bug
620 will be fixed (someday).</para>
626 <sect2 id="pre-supposed-other-tools">
627 <title>Other useful tools</title>
632 <indexterm><primary>pre-supposed: flex</primary></indexterm>
633 <indexterm><primary>flex, pre-supposed</primary></indexterm>
636 <para>This is a quite-a-bit-better-than-Lex lexer. Used
637 to build a couple of utilities in
638 <literal>glafp-utils</literal>. Depending on your
639 operating system, the supplied <command>lex</command> may
640 or may not work; you should get the GNU version.</para>
645 <para>More tools are required if you want to format the documentation
646 that comes with GHC and other fptools projects. See <xref
647 linkend="building-docs"/>.</para>
651 <sect1 id="sec-building-from-source">
652 <title>Building from source</title>
654 <indexterm><primary>Building from source</primary></indexterm>
655 <indexterm><primary>Source, building from</primary></indexterm>
657 <para>“I just want to build it!”</para>
659 <para>No problem. This recipe should build and install a working GHC with
660 all the default settings. (unless you're
661 on Windows, in which case go to <xref linkend="winbuild" />).</para>
663 <screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
667 $ make install</screen>
669 <para>For GHC, this will do a 2-stage bootstrap build of the
670 compiler, with profiling libraries, and install the
671 results in the default location (under <filename>/usr/local</filename> on
672 Unix, for example).</para>
674 <para>The <literal>configure</literal> script is a standard GNU
675 <literal>autoconf</literal> script, and accepts the usual options for
676 changing install locations and the like. Run
677 <literal>./configure --help</literal> for a list of options.</para>
679 <para>If you want to do anything at all non-standard, or you
680 want to do some development, read on...</para>
683 <sect1 id="quick-start">
684 <title>Quick start for GHC developers</title>
686 <para>This section is a copy of the file
687 <literal>ghc/HACKING</literal> from the GHC source tree. It describes
688 how to get started with setting up your build tree for developing GHC
689 or its libraries, and how to start building.</para>
696 <sect1 id="sec-working-with-the-build-system">
697 <title>Working with the build system</title>
699 <para>This rest of this guide is intended for duffers like me, who
700 aren't really interested in Makefiles and systems configurations,
701 but who need a mental model of the interlocking pieces so that
702 they can make them work, extend them consistently when adding new
703 software, and lay hands on them gently when they don't
706 <sect2 id="sec-source-tree">
707 <title>Your source tree</title>
709 <para>The source code is held in your <emphasis>source
710 tree</emphasis>. The root directory of your source tree
711 <emphasis>must</emphasis> contain the following directories and
716 <para><filename>Makefile</filename>: the root
721 <para><filename>mk/</filename>: the directory that contains
722 the main Makefile code, shared by all the
723 <literal>fptools</literal> software.</para>
727 <para><filename>configure.ac</filename>,
728 <filename>config.sub</filename>,
729 <filename>config.guess</filename>: these files support the
730 configuration process.</para>
734 <para><filename>install-sh</filename>.</para>
738 <para>All the other directories are individual
739 <emphasis>projects</emphasis> of the <literal>fptools</literal>
740 system—for example, the Glasgow Haskell Compiler
741 (<literal>ghc</literal>), the Happy parser generator
742 (<literal>happy</literal>), the <literal>nofib</literal>
743 benchmark suite, and so on. You can have zero or more of these.
744 Needless to say, some of them are needed to build others.</para>
746 <para>The important thing to remember is that even if you want
747 only one project (<literal>happy</literal>, say), you must have
748 a source tree whose root directory contains
749 <filename>Makefile</filename>, <filename>mk/</filename>,
750 <filename>configure.ac</filename>, and the project(s) you want
751 (<filename>happy/</filename> in this case). You cannot get by
752 with just the <filename>happy/</filename> directory.</para>
756 <title>Build trees</title>
757 <indexterm><primary>build trees</primary></indexterm>
758 <indexterm><primary>link trees, for building</primary></indexterm>
760 <para>If you just want to build the software once on a single
761 platform, then your source tree can also be your build tree, and
762 you can skip the rest of this section.</para>
764 <para>We often want to build multiple versions of our software
765 for different architectures, or with different options
766 (e.g. profiling). It's very desirable to share a single copy of
767 the source code among all these builds.</para>
769 <para>So for every source tree we have zero or more
770 <emphasis>build trees</emphasis>. Each build tree is initially
771 an exact copy of the source tree, except that each file is a
772 symbolic link to the source file, rather than being a copy of
773 the source file. There are “standard” Unix
774 utilities that make such copies, so standard that they go by
776 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
777 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
778 are two (If you don't have either, the source distribution
779 includes sources for the X11
780 <command>lndir</command>—check out
781 <filename>fptools/glafp-utils/lndir</filename>). See <xref
782 linkend="sec-storysofar"/> for a typical invocation.</para>
784 <para>The build tree does not need to be anywhere near the
785 source tree in the file system. Indeed, one advantage of
786 separating the build tree from the source is that the build tree
787 can be placed in a non-backed-up partition, saving your systems
788 support people from backing up untold megabytes of
789 easily-regenerated, and rapidly-changing, gubbins. The golden
790 rule is that (with a single exception—<xref
791 linkend="sec-build-config"/>) <emphasis>absolutely everything in
792 the build tree is either a symbolic link to the source tree, or
793 else is mechanically generated</emphasis>. It should be
794 perfectly OK for your build tree to vanish overnight; an hour or
795 two compiling and you're on the road again.</para>
797 <para>You need to be a bit careful, though, that any new files
798 you create (if you do any development work) are in the source
799 tree, not a build tree!</para>
801 <para>Remember, that the source files in the build tree are
802 <emphasis>symbolic links</emphasis> to the files in the source
803 tree. (The build tree soon accumulates lots of built files like
804 <filename>Foo.o</filename>, as well.) You can
805 <emphasis>delete</emphasis> a source file from the build tree
806 without affecting the source tree (though it's an odd thing to
807 do). On the other hand, if you <emphasis>edit</emphasis> a
808 source file from the build tree, you'll edit the source-tree
809 file directly. (You can set up Emacs so that if you edit a
810 source file from the build tree, Emacs will silently create an
811 edited copy of the source file in the build tree, leaving the
812 source file unchanged; but the danger is that you think you've
813 edited the source file whereas actually all you've done is edit
814 the build-tree copy. More commonly you do want to edit the
817 <para>Like the source tree, the top level of your build tree
818 must be (a linked copy of) the root directory of the
819 <literal>fptools</literal> suite. Inside Makefiles, the root of
820 your build tree is called
821 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
822 In the rest of this document path names are relative to
823 <constant>$(FPTOOLS_TOP)</constant> unless
824 otherwise stated. For example, the file
825 <filename>ghc/mk/target.mk</filename> is actually
826 <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
829 <sect2 id="sec-build-config">
830 <title>Getting the build you want</title>
832 <para>When you build <literal>fptools</literal> you will be
833 compiling code on a particular <emphasis>host
834 platform</emphasis>, to run on a particular <emphasis>target
835 platform</emphasis> (usually the same as the host
836 platform)<indexterm><primary>platform</primary></indexterm>.
837 The difficulty is that there are minor differences between
838 different platforms; minor, but enough that the code needs to be
839 a bit different for each. There are some big differences too:
840 for a different architecture we need to build GHC with a
841 different native-code generator.</para>
843 <para>There are also knobs you can turn to control how the
844 <literal>fptools</literal> software is built. For example, you
845 might want to build GHC optimised (so that it runs fast) or
846 unoptimised (so that you can compile it fast after you've
847 modified it. Or, you might want to compile it with debugging on
848 (so that extra consistency-checking code gets included) or off.
851 <para>All of this stuff is called the
852 <emphasis>configuration</emphasis> of your build. You set the
853 configuration using a three-step process.</para>
857 <term>Step 1: get ready for configuration.</term>
859 <para>NOTE: if you're starting from a source distribution,
860 rather than darcs sources, you can skip this step.</para>
862 <para>Change directory to
863 <constant>$(FPTOOLS_TOP)</constant> and
864 issue the command</para>
865 <screen>$ autoreconf</screen>
866 <indexterm><primary>autoreconf</primary></indexterm>
867 <para>(with no arguments). This GNU program (recursively) converts
868 <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
869 <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
870 to a shell script called
871 <filename>$(FPTOOLS_TOP)/configure</filename>.
872 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
873 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
874 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
875 a message like "No rule to make target 'mk/config.h.in'".
878 <para>Some projects, including GHC, have their own configure script.
879 <command>autoreconf</command> takes care of that, too, so all you have
880 to do is calling <command>autoreconf</command> in the top-level directory
881 <filename>$(FPTOOLS_TOP)</filename>.</para>
883 <para>These steps are completely platform-independent; they just mean
884 that the human-written files (<filename>configure.ac</filename> and
885 <filename>aclocal.m4</filename>) can be short, although the resulting
886 files (the <command>configure</command> shell scripts and the C header
887 template <filename>mk/config.h.in</filename>) are long.</para>
892 <term>Step 2: system configuration.</term>
894 <para>Runs the newly-created <command>configure</command>
897 <screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
899 <para><command>configure</command>'s mission is to scurry
900 round your computer working out what architecture it has,
901 what operating system, whether it has the
902 <function>vfork</function> system call, where
903 <command>tar</command> is kept, whether
904 <command>gcc</command> is available, where various obscure
905 <literal>#include</literal> files are, whether it's a
906 leap year, and what the systems manager had for lunch. It
907 communicates these snippets of information in two
914 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
916 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
917 substituting for things between
918 “<literal>@</literal>” brackets. So,
919 “<literal>@HaveGcc@</literal>” will be
920 replaced by “<literal>YES</literal>” or
921 “<literal>NO</literal>” depending on what
922 <command>configure</command> finds.
923 <filename>mk/config.mk</filename> is included by every
924 Makefile (directly or indirectly), so the
925 configuration information is thereby communicated to
926 all Makefiles.</para>
931 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
933 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
934 The latter is <literal>#include</literal>d by
935 various C programs, which can thereby make use of
936 configuration information.</para>
940 <para><command>configure</command> takes some optional
941 arguments. Use <literal>./configure --help</literal> to
942 get a list of the available arguments. Here are some of
943 the ones you might need:</para>
947 <term><literal>--with-ghc=<parameter>path</parameter></literal>
948 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
951 <para>Specifies the path to an installed GHC which
952 you would like to use. This compiler will be used
953 for compiling GHC-specific code (eg. GHC itself).
954 This option <emphasis>cannot</emphasis> be specified
955 using <filename>build.mk</filename> (see later),
956 because <command>configure</command> needs to
957 auto-detect the version of GHC you're using. The
958 default is to look for a compiler named
959 <literal>ghc</literal> in your path.</para>
964 <term><literal>--with-hc=<parameter>path</parameter></literal>
965 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
968 <para>Specifies the path to any installed Haskell
969 compiler. This compiler will be used for compiling
970 generic Haskell code. The default is to use
971 <literal>ghc</literal>.</para>
976 <term><literal>--with-gcc=<parameter>path</parameter></literal>
977 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
980 <para>Specifies the path to the installed GCC. This
981 compiler will be used to compile all C files,
982 <emphasis>except</emphasis> any generated by the
983 installed Haskell compiler, which will have its own
984 idea of which C compiler (if any) to use. The
985 default is to use <literal>gcc</literal>.</para>
993 <term>Step 3: build configuration.</term>
995 <para>Next, you say how this build of
996 <literal>fptools</literal> is to differ from the standard
997 defaults by creating a new file
998 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
999 <emphasis>in the build tree</emphasis>. This file is the
1000 one and only file you edit in the build tree, precisely
1001 because it says how this build differs from the source.
1002 (Just in case your build tree does die, you might want to
1003 keep a private directory of <filename>build.mk</filename>
1004 files, and use a symbolic link in each build tree to point
1005 to the appropriate one.) So
1006 <filename>mk/build.mk</filename> never exists in the
1007 source tree—you create one in each build tree from
1008 the template. We'll discuss what to put in it
1014 <para>And that's it for configuration. Simple, eh?</para>
1016 <para>What do you put in your build-specific configuration file
1017 <filename>mk/build.mk</filename>? <emphasis>For almost all
1018 purposes all you will do is put make variable definitions that
1019 override those in</emphasis>
1020 <filename>mk/config.mk.in</filename>. The whole point of
1021 <filename>mk/config.mk.in</filename>—and its derived
1022 counterpart <filename>mk/config.mk</filename>—is to define
1023 the build configuration. It is heavily commented, as you will
1024 see if you look at it. So generally, what you do is look at
1025 <filename>mk/config.mk.in</filename>, and add definitions in
1026 <filename>mk/build.mk</filename> that override any of the
1027 <filename>config.mk</filename> definitions that you want to
1028 change. (The override occurs because the main boilerplate file,
1029 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1030 includes <filename>build.mk</filename> after
1031 <filename>config.mk</filename>.)</para>
1033 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1034 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1036 <para>For example, <filename>config.mk.in</filename> contains
1037 the definition:</para>
1039 <programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
1041 <para>The accompanying comment explains that this is the list of
1042 flags passed to GHC when building GHC itself. For doing
1043 development, it is wise to add <literal>-DDEBUG</literal>, to
1044 enable debugging code. So you would add the following to
1045 <filename>build.mk</filename>:</para>
1047 <para>or, if you prefer,</para>
1049 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
1051 <para>GNU <command>make</command> allows existing definitions to
1052 have new text appended using the “<literal>+=</literal>”
1053 operator, which is quite a convenient feature.)</para>
1055 <para>If you want to remove the <literal>-O</literal> as well (a
1056 good idea when developing, because the turn-around cycle gets a
1057 lot quicker), you can just override
1058 <literal>GhcLibHcOpts</literal> altogether:</para>
1060 <programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
1062 <para>When reading <filename>config.mk.in</filename>, remember
1063 that anything between “@...@” signs is going to be substituted
1064 by <command>configure</command> later. You
1065 <emphasis>can</emphasis> override the resulting definition if
1066 you want, but you need to be a bit surer what you are doing.
1067 For example, there's a line that says:</para>
1069 <programlisting>TAR = @TarCmd@</programlisting>
1071 <para>This defines the Make variables <constant>TAR</constant>
1072 to the pathname for a <command>tar</command> that
1073 <command>configure</command> finds somewhere. If you have your
1074 own pet <command>tar</command> you want to use instead, that's
1075 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1077 <programlisting>TAR = mytar</programlisting>
1079 <para>You do not <emphasis>have</emphasis> to have a
1080 <filename>mk/build.mk</filename> file at all; if you don't,
1081 you'll get all the default settings from
1082 <filename>mk/config.mk.in</filename>.</para>
1084 <para>You can also use <filename>build.mk</filename> to override
1085 anything that <command>configure</command> got wrong. One place
1086 where this happens often is with the definition of
1087 <constant>FPTOOLS_TOP_ABS</constant>: this
1088 variable is supposed to be the canonical path to the top of your
1089 source tree, but if your system uses an automounter then the
1090 correct directory is hard to find automatically. If you find
1091 that <command>configure</command> has got it wrong, just put the
1092 correct definition in <filename>build.mk</filename>.</para>
1096 <sect2 id="sec-storysofar">
1097 <title>The story so far</title>
1099 <para>Let's summarise the steps you need to carry to get
1100 yourself a fully-configured build tree from scratch.</para>
1104 <para> Get your source tree from somewhere (darcs repository
1105 or source distribution). Say you call the root directory
1106 <filename>myfptools</filename> (it does not have to be
1107 called <filename>fptools</filename>). Make sure that you
1108 have the essential files (see <xref
1109 linkend="sec-source-tree"/>).</para>
1114 <para>(Optional) Use <command>lndir</command> or
1115 <command>mkshadowdir</command> to create a build tree.</para>
1117 <screen>$ cd myfptools
1118 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
1120 <para>(N.B. <command>mkshadowdir</command>'s first argument
1121 is taken relative to its second.) You probably want to give
1122 the build tree a name that suggests its main defining
1123 characteristic (in your mind at least), in case you later
1128 <para>Change directory to the build tree. Everything is
1129 going to happen there now.</para>
1131 <screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
1136 <para>Prepare for system configuration:</para>
1138 <screen>$ autoreconf</screen>
1140 <para>(You can skip this step if you are starting from a
1141 source distribution, and you already have
1142 <filename>configure</filename> and
1143 <filename>mk/config.h.in</filename>.)</para>
1147 <para>Do system configuration:</para>
1149 <screen>$ ./configure</screen>
1151 <para>Don't forget to check whether you need to add any
1152 arguments to <literal>configure</literal>; for example, a
1153 common requirement is to specify which GHC to use with
1154 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1158 <para>Create the file <filename>mk/build.mk</filename>,
1159 adding definitions for your desired configuration
1162 <screen>$ emacs mk/build.mk</screen>
1166 <para>You can make subsequent changes to
1167 <filename>mk/build.mk</filename> as often as you like. You do
1168 not have to run any further configuration programs to make these
1169 changes take effect. In theory you should, however, say
1170 <command>gmake clean</command>, <command>gmake all</command>,
1171 because configuration option changes could affect
1172 anything—but in practice you are likely to know what's
1177 <title>Making things</title>
1179 <para>At this point you have made yourself a fully-configured
1180 build tree, so you are ready to start building real
1183 <para>The first thing you need to know is that <emphasis>you
1184 must use GNU <command>make</command>, usually called
1185 <command>gmake</command>, not standard Unix
1186 <command>make</command></emphasis>. If you use standard Unix
1187 <command>make</command> you will get all sorts of error messages
1188 (but no damage) because the <literal>fptools</literal>
1189 <command>Makefiles</command> use GNU <command>make</command>'s
1190 facilities extensively.</para>
1192 <para>To just build the whole thing, <command>cd</command> to
1193 the top of your <literal>fptools</literal> tree and type
1194 <command>gmake</command>. This will prepare the tree and build
1195 the various projects in the correct order.</para>
1198 <sect2 id="sec-bootstrapping">
1199 <title>Bootstrapping GHC</title>
1201 <para>GHC requires a 2-stage bootstrap in order to provide
1202 full functionality, including GHCi. By a 2-stage bootstrap, we
1203 mean that the compiler is built once using the installed GHC,
1204 and then again using the compiler built in the first stage. You
1205 can also build a stage 3 compiler, but this normally isn't
1206 necessary except to verify that the stage 2 compiler is working
1209 <para>Note that when doing a bootstrap, the stage 1 compiler
1210 must be built, followed by the runtime system and libraries, and
1211 then the stage 2 compiler. The correct ordering is implemented
1212 by the top-level fptools <filename>Makefile</filename>, so if
1213 you want everything to work automatically it's best to start
1214 <command>make</command> from the top of the tree. When building
1215 GHC, the top-level fptools <filename>Makefile</filename> is set
1216 up to do a 2-stage bootstrap by default (when you say
1217 <command>make</command>). Some other targets it supports
1224 <para>Build everything as normal, including the stage 1
1232 <para>Build the stage 2 compiler only.</para>
1239 <para>Build the stage 3 compiler only.</para>
1244 <term>bootstrap</term> <term>bootstrap2</term>
1246 <para>Build stage 1 followed by stage 2.</para>
1251 <term>bootstrap3</term>
1253 <para>Build stages 1, 2 and 3.</para>
1258 <term>install</term>
1260 <para>Install everything, including the compiler built in
1261 stage 2. To override the stage, say <literal>make install
1262 stage=<replaceable>n</replaceable></literal> where
1263 <replaceable>n</replaceable> is the stage to install.</para>
1268 <para>The top-level <filename>Makefile</filename> also arranges
1269 to do the appropriate <literal>make boot</literal> steps (see
1270 below) before actually building anything.</para>
1272 <para>The <literal>stage1</literal>, <literal>stage2</literal>
1273 and <literal>stage3</literal> targets also work in the
1274 <literal>ghc/compiler</literal> directory, but don't forget that
1275 each stage requires its own <literal>make boot</literal> step:
1276 for example, you must do</para>
1278 <screen>$ make boot stage=2</screen>
1280 <para>before <literal>make stage2</literal> in
1281 <literal>ghc/compiler</literal>.</para>
1284 <sect2 id="sec-standard-targets">
1285 <title>Standard Targets</title>
1286 <indexterm><primary>targets, standard makefile</primary></indexterm>
1287 <indexterm><primary>makefile targets</primary></indexterm>
1289 <para>In any directory you should be able to make the following:</para>
1293 <term><literal>boot</literal></term>
1295 <para>does the one-off preparation required to get ready
1296 for the real work. Notably, it does <command>gmake
1297 depend</command> in all directories that contain programs.
1298 It also builds the necessary tools for compilation to
1301 <para>Invoking the <literal>boot</literal> target
1302 explicitly is not normally necessary. From the top-level
1303 <literal>fptools</literal> directory, invoking
1304 <literal>gmake</literal> causes <literal>gmake boot
1305 all</literal> to be invoked in each of the project
1306 subdirectories, in the order specified by
1307 <literal>$(AllTargets)</literal> in
1308 <literal>config.mk</literal>.</para>
1310 <para>If you're working in a subdirectory somewhere and
1311 need to update the dependencies, <literal>gmake
1312 boot</literal> is a good way to do it.</para>
1317 <term><literal>all</literal></term>
1319 <para>makes all the final target(s) for this Makefile.
1320 Depending on which directory you are in a “final
1321 target” may be an executable program, a library
1322 archive, a shell script, or a Postscript file. Typing
1323 <command>gmake</command> alone is generally the same as
1324 typing <command>gmake all</command>.</para>
1329 <term><literal>install</literal></term>
1331 <para>installs the things built by <literal>all</literal>
1332 (except for the documentation). Where does it install
1333 them? That is specified by
1334 <filename>mk/config.mk.in</filename>; you can override it
1335 in <filename>mk/build.mk</filename>, or by running
1336 <command>configure</command> with command-line arguments
1337 like <literal>--bindir=/home/simonpj/bin</literal>; see
1338 <literal>./configure --help</literal> for the full
1344 <term><literal>install-docs</literal></term>
1346 <para>installs the documentation. Otherwise behaves just
1347 like <literal>install</literal>.</para>
1352 <term><literal>uninstall</literal></term>
1354 <para>reverses the effect of
1355 <literal>install</literal>.</para>
1360 <term><literal>clean</literal></term>
1362 <para>Delete all files from the current directory that are
1363 normally created by building the program. Don't delete
1364 the files that record the configuration, or files
1365 generated by <command>gmake boot</command>. Also preserve
1366 files that could be made by building, but normally aren't
1367 because the distribution comes with them.</para>
1372 <term><literal>distclean</literal></term>
1374 <para>Delete all files from the current directory that are
1375 created by configuring or building the program. If you
1376 have unpacked the source and built the program without
1377 creating any other files, <literal>make
1378 distclean</literal> should leave only the files that were
1379 in the distribution.</para>
1384 <term><literal>mostlyclean</literal></term>
1386 <para>Like <literal>clean</literal>, but may refrain from
1387 deleting a few files that people normally don't want to
1393 <term><literal>maintainer-clean</literal></term>
1395 <para>Delete everything from the current directory that
1396 can be reconstructed with this Makefile. This typically
1397 includes everything deleted by
1398 <literal>distclean</literal>, plus more: C source files
1399 produced by Bison, tags tables, Info files, and so
1402 <para>One exception, however: <literal>make
1403 maintainer-clean</literal> should not delete
1404 <filename>configure</filename> even if
1405 <filename>configure</filename> can be remade using a rule
1406 in the <filename>Makefile</filename>. More generally,
1407 <literal>make maintainer-clean</literal> should not delete
1408 anything that needs to exist in order to run
1409 <filename>configure</filename> and then begin to build the
1415 <term><literal>check</literal></term>
1417 <para>run the test suite.</para>
1422 <para>All of these standard targets automatically recurse into
1423 sub-directories. Certain other standard targets do not:</para>
1427 <term><literal>configure</literal></term>
1429 <para>is only available in the root directory
1430 <constant>$(FPTOOLS_TOP)</constant>; it has
1431 been discussed in <xref
1432 linkend="sec-build-config"/>.</para>
1437 <term><literal>depend</literal></term>
1439 <para>make a <filename>.depend</filename> file in each
1440 directory that needs it. This <filename>.depend</filename>
1441 file contains mechanically-generated dependency
1442 information; for example, suppose a directory contains a
1443 Haskell source module <filename>Foo.lhs</filename> which
1444 imports another module <literal>Baz</literal>. Then the
1445 generated <filename>.depend</filename> file will contain
1446 the dependency:</para>
1448 <programlisting>Foo.o : Baz.hi</programlisting>
1450 <para>which says that the object file
1451 <filename>Foo.o</filename> depends on the interface file
1452 <filename>Baz.hi</filename> generated by compiling module
1453 <literal>Baz</literal>. The <filename>.depend</filename>
1454 file is automatically included by every Makefile.</para>
1459 <term><literal>binary-dist</literal></term>
1461 <para>make a binary distribution. This is the target we
1462 use to build the binary distributions of GHC and
1468 <term><literal>dist</literal></term>
1470 <para>make a source distribution. Note that this target
1471 does “make distclean” as part of its work;
1472 don't use it if you want to keep what you've built.</para>
1477 <para>Most <filename>Makefile</filename>s have targets other
1478 than these. You can discover them by looking in the
1479 <filename>Makefile</filename> itself.</para>
1483 <title>Using a project from the build tree</title>
1485 <para>If you want to build GHC (say) and just use it direct from
1486 the build tree without doing <literal>make install</literal>
1487 first, you can run the in-place driver script:
1488 <filename>ghc/compiler/ghc-inplace</filename>.</para>
1490 <para> Do <emphasis>NOT</emphasis> use
1491 <filename>ghc/compiler/ghc</filename>, or
1492 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
1493 scripts intended for installation, and contain hard-wired paths
1494 to the installed libraries, rather than the libraries in the
1497 <para>Happy can similarly be run from the build tree, using
1498 <filename>happy/src/happy-inplace</filename>, and similarly for
1499 Alex and Haddock.</para>
1503 <title>Fast Making</title>
1505 <indexterm><primary>fastmake</primary></indexterm>
1506 <indexterm><primary>dependencies, omitting</primary></indexterm>
1507 <indexterm><primary>FAST, makefile variable</primary></indexterm>
1509 <para>Sometimes the dependencies get in the way: if you've made
1510 a small change to one file, and you're absolutely sure that it
1511 won't affect anything else, but you know that
1512 <command>make</command> is going to rebuild everything anyway,
1513 the following hack may be useful:</para>
1515 <screen>$ gmake FAST=YES</screen>
1517 <para>This tells the make system to ignore dependencies and just
1518 build what you tell it to. In other words, it's equivalent to
1519 temporarily removing the <filename>.depend</filename> file in
1520 the current directory (where <command>mkdependHS</command> and
1521 friends store their dependency information).</para>
1523 <para>A bit of history: GHC used to come with a
1524 <command>fastmake</command> script that did the above job, but
1525 GNU make provides the features we need to do it without
1526 resorting to a script. Also, we've found that fastmaking is
1527 less useful since the advent of GHC's recompilation checker (see
1528 the User's Guide section on "Separate Compilation").</para>
1532 <sect1 id="sec-makefile-arch">
1533 <title>The <filename>Makefile</filename> architecture</title>
1534 <indexterm><primary>makefile architecture</primary></indexterm>
1536 <para><command>make</command> is great if everything
1537 works—you type <command>gmake install</command> and lo! the
1538 right things get compiled and installed in the right places. Our
1539 goal is to make this happen often, but somehow it often doesn't;
1540 instead some weird error message eventually emerges from the
1541 bowels of a directory you didn't know existed.</para>
1543 <para>The purpose of this section is to give you a road-map to
1544 help you figure out what is going right and what is going
1548 <title>Debugging</title>
1550 <para>Debugging <filename>Makefile</filename>s is something of a
1551 black art, but here's a couple of tricks that we find
1552 particularly useful. The following command allows you to see
1553 the contents of any make variable in the context of the current
1554 <filename>Makefile</filename>:</para>
1556 <screen>$ make show VALUE=HS_SRCS</screen>
1558 <para>where you can replace <literal>HS_SRCS</literal> with the
1559 name of any variable you wish to see the value of.</para>
1561 <para>GNU make has a <option>-d</option> option which generates
1562 a dump of the decision procedure used to arrive at a conclusion
1563 about which files should be recompiled. Sometimes useful for
1564 tracking down problems with superfluous or missing
1565 recompilations.</para>
1569 <title>A small project</title>
1571 <para>To get started, let us look at the
1572 <filename>Makefile</filename> for an imaginary small
1573 <literal>fptools</literal> project, <literal>small</literal>.
1574 Each project in <literal>fptools</literal> has its own directory
1575 in <constant>FPTOOLS_TOP</constant>, so the
1576 <literal>small</literal> project will have its own directory
1577 <constant>FPOOLS_TOP/small/</constant>. Inside the
1578 <filename>small/</filename> directory there will be a
1579 <filename>Makefile</filename>, looking something like
1582 <indexterm><primary>Makefile, minimal</primary></indexterm>
1584 <programlisting># Makefile for fptools project "small"
1587 include $(TOP)/mk/boilerplate.mk
1589 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1592 include $(TOP)/target.mk</programlisting>
1594 <para>this <filename>Makefile</filename> has three
1599 <para>The first section includes
1602 One of the most important
1603 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
1604 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
1609 a file of “boilerplate” code from the level
1610 above (which in this case will be
1611 <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
1612 As its name suggests, <filename>boilerplate.mk</filename>
1613 consists of a large quantity of standard
1614 <filename>Makefile</filename> code. We discuss this
1615 boilerplate in more detail in <xref linkend="sec-boiler"/>.
1616 <indexterm><primary>include, directive in
1617 Makefiles</primary></indexterm> <indexterm><primary>Makefile
1618 inclusion</primary></indexterm></para>
1620 <para>Before the <literal>include</literal> statement, you
1621 must define the <command>make</command> variable
1622 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
1623 to be the directory containing the <filename>mk</filename>
1624 directory in which the <filename>boilerplate.mk</filename>
1625 file is. It is <emphasis>not</emphasis> OK to simply say</para>
1627 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
1630 <para>Why? Because the <filename>boilerplate.mk</filename>
1631 file needs to know where it is, so that it can, in turn,
1632 <literal>include</literal> other files. (Unfortunately,
1633 when an <literal>include</literal>d file does an
1634 <literal>include</literal>, the filename is treated relative
1635 to the directory in which <command>gmake</command> is being
1636 run, not the directory in which the
1637 <literal>include</literal>d sits.) In general,
1638 <emphasis>every file <filename>foo.mk</filename> assumes
1640 <filename>$(TOP)/mk/foo.mk</filename>
1641 refers to itself.</emphasis> It is up to the
1642 <filename>Makefile</filename> doing the
1643 <literal>include</literal> to ensure this is the case.</para>
1645 <para>Files intended for inclusion in other
1646 <filename>Makefile</filename>s are written to have the
1647 following property: <emphasis>after
1648 <filename>foo.mk</filename> is <literal>include</literal>d,
1649 it leaves <constant>TOP</constant> containing the same value
1650 as it had just before the <literal>include</literal>
1651 statement</emphasis>. In our example, this invariant
1652 guarantees that the <literal>include</literal> for
1653 <filename>target.mk</filename> will look in the same
1654 directory as that for <filename>boilerplate.mk</filename>.</para>
1658 <para> The second section defines the following standard
1659 <command>make</command> variables:
1660 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
1661 (the source files from which is to be built), and
1662 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
1663 (the executable binary to be built). We will discuss in
1664 more detail what the “standard variables” are,
1665 and how they affect what happens, in <xref
1666 linkend="sec-targets"/>.</para>
1668 <para>The definition for <constant>SRCS</constant> uses the
1669 useful GNU <command>make</command> construct
1670 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
1671 which expands to a list of all the files matching the
1672 pattern <literal>pat</literal> in the current directory. In
1673 this example, <constant>SRCS</constant> is set to the list
1674 of all the <filename>.lhs</filename> and
1675 <filename>.c</filename> files in the directory. (Let's
1676 suppose there is one of each, <filename>Foo.lhs</filename>
1677 and <filename>Baz.c</filename>.)</para>
1681 <para>The last section includes a second file of standard
1683 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
1684 It contains the rules that tell <command>gmake</command> how
1685 to make the standard targets (<xref
1686 linkend="sec-standard-targets"/>). Why, you ask, can't this
1687 standard code be part of
1688 <filename>boilerplate.mk</filename>? Good question. We
1689 discuss the reason later, in <xref
1690 linkend="sec-boiler-arch"/>.</para>
1692 <para>You do not <emphasis>have</emphasis> to
1693 <literal>include</literal> the
1694 <filename>target.mk</filename> file. Instead, you can write
1695 rules of your own for all the standard targets. Usually,
1696 though, you will find quite a big payoff from using the
1697 canned rules in <filename>target.mk</filename>; the price
1698 tag is that you have to understand what canned rules get
1699 enabled, and what they do (<xref
1700 linkend="sec-targets"/>).</para>
1704 <para>In our example <filename>Makefile</filename>, most of the
1705 work is done by the two <literal>include</literal>d files. When
1706 you say <command>gmake all</command>, the following things
1711 <para><command>gmake</command> figures out that the object
1712 files are <filename>Foo.o</filename> and
1713 <filename>Baz.o</filename>.</para>
1717 <para>It uses a boilerplate pattern rule to compile
1718 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
1719 using a Haskell compiler. (Which one? That is set in the
1720 build configuration.)</para>
1724 <para>It uses another standard pattern rule to compile
1725 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
1726 using a C compiler. (Ditto.)</para>
1730 <para>It links the resulting <filename>.o</filename> files
1731 together to make <literal>small</literal>, using the Haskell
1732 compiler to do the link step. (Why not use
1733 <command>ld</command>? Because the Haskell compiler knows
1734 what standard libraries to link in. How did
1735 <command>gmake</command> know to use the Haskell compiler to
1736 do the link, rather than the C compiler? Because we set the
1737 variable <constant>HS_PROG</constant> rather than
1738 <constant>C_PROG</constant>.)</para>
1742 <para>All <filename>Makefile</filename>s should follow the above
1743 three-section format.</para>
1747 <title>A larger project</title>
1749 <para>Larger projects are usually structured into a number of
1750 sub-directories, each of which has its own
1751 <filename>Makefile</filename>. (In very large projects, this
1752 sub-structure might be iterated recursively, though that is
1753 rare.) To give you the idea, here's part of the directory
1754 structure for the (rather large) GHC project:</para>
1756 <programlisting>$(FPTOOLS_TOP)/ghc/
1763 ...source files for documentation...
1766 ...source files for driver...
1769 parser/...source files for parser...
1770 renamer/...source files for renamer...
1771 ...etc...</programlisting>
1773 <para>The sub-directories <filename>docs</filename>,
1774 <filename>driver</filename>, <filename>compiler</filename>, and
1775 so on, each contains a sub-component of GHC, and each has its
1776 own <filename>Makefile</filename>. There must also be a
1777 <filename>Makefile</filename> in
1778 <filename>$(FPTOOLS_TOP)/ghc</filename>.
1779 It does most of its work by recursively invoking
1780 <command>gmake</command> on the <filename>Makefile</filename>s
1781 in the sub-directories. We say that
1782 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
1783 <filename>Makefile</filename></emphasis>, because it does little
1784 except organise its children, while the
1785 <filename>Makefile</filename>s in the sub-directories are all
1786 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
1787 principle the sub-directories might themselves contain a
1788 non-leaf <filename>Makefile</filename> and several
1789 sub-sub-directories, but that does not happen in GHC.)</para>
1791 <para>The <filename>Makefile</filename> in
1792 <filename>ghc/compiler</filename> is considered a leaf
1793 <filename>Makefile</filename> even though the
1794 <filename>ghc/compiler</filename> has sub-directories, because
1795 these sub-directories do not themselves have
1796 <filename>Makefile</filename>s in them. They are just used to
1797 structure the collection of modules that make up GHC, but all
1798 are managed by the single <filename>Makefile</filename> in
1799 <filename>ghc/compiler</filename>.</para>
1801 <para>You will notice that <filename>ghc/</filename> also
1802 contains a directory <filename>ghc/mk/</filename>. It contains
1803 GHC-specific <filename>Makefile</filename> boilerplate code.
1804 More precisely:</para>
1808 <para><filename>ghc/mk/boilerplate.mk</filename> is included
1809 at the top of <filename>ghc/Makefile</filename>, and of all
1810 the leaf <filename>Makefile</filename>s in the
1811 sub-directories. It in turn <literal>include</literal>s the
1812 main boilerplate file
1813 <filename>mk/boilerplate.mk</filename>.</para>
1817 <para><filename>ghc/mk/target.mk</filename> is
1818 <literal>include</literal>d at the bottom of
1819 <filename>ghc/Makefile</filename>, and of all the leaf
1820 <filename>Makefile</filename>s in the sub-directories. It
1821 in turn <literal>include</literal>s the file
1822 <filename>mk/target.mk</filename>.</para>
1826 <para>So these two files are the place to look for GHC-wide
1827 customisation of the standard boilerplate.</para>
1830 <sect2 id="sec-boiler-arch">
1831 <title>Boilerplate architecture</title>
1832 <indexterm><primary>boilerplate architecture</primary></indexterm>
1834 <para>Every <filename>Makefile</filename> includes a
1835 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
1836 file at the top, and
1837 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
1838 file at the bottom. In this section we discuss what is in these
1839 files, and why there have to be two of them. In general:</para>
1843 <para><filename>boilerplate.mk</filename> consists of:</para>
1847 <para><emphasis>Definitions of millions of
1848 <command>make</command> variables</emphasis> that
1849 collectively specify the build configuration. Examples:
1850 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1851 the options to feed to the Haskell compiler;
1852 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
1853 the sub-directories to enable within the
1854 <literal>nofib</literal> project;
1855 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
1856 the name of the Haskell compiler to use when compiling
1857 GHC in the <literal>ghc</literal> project.</para>
1861 <para><emphasis>Standard pattern rules</emphasis> that
1862 tell <command>gmake</command> how to construct one file
1863 from another.</para>
1867 <para><filename>boilerplate.mk</filename> needs to be
1868 <literal>include</literal>d at the <emphasis>top</emphasis>
1869 of each <filename>Makefile</filename>, so that the user can
1870 replace the boilerplate definitions or pattern rules by
1871 simply giving a new definition or pattern rule in the
1872 <filename>Makefile</filename>. <command>gmake</command>
1873 simply takes the last definition as the definitive one.</para>
1875 <para>Instead of <emphasis>replacing</emphasis> boilerplate
1876 definitions, it is also quite common to
1877 <emphasis>augment</emphasis> them. For example, a
1878 <filename>Makefile</filename> might say:</para>
1880 <programlisting>SRC_HC_OPTS += -O</programlisting>
1882 <para>thereby adding “<option>-O</option>” to
1884 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
1888 <para><filename>target.mk</filename> contains
1889 <command>make</command> rules for the standard targets
1890 described in <xref linkend="sec-standard-targets"/>. These
1891 rules are selectively included, depending on the setting of
1892 certain <command>make</command> variables. These variables
1893 are usually set in the middle section of the
1894 <filename>Makefile</filename> between the two
1895 <literal>include</literal>s.</para>
1897 <para><filename>target.mk</filename> must be included at the
1898 end (rather than being part of
1899 <filename>boilerplate.mk</filename>) for several tiresome
1905 <para><command>gmake</command> commits target and
1906 dependency lists earlier than it should. For example,
1907 <filename>target.mk</filename> has a rule that looks
1910 <programlisting>$(HS_PROG) : $(OBJS)
1911 $(HC) $(LD_OPTS) $< -o $@</programlisting>
1913 <para>If this rule was in
1914 <filename>boilerplate.mk</filename> then
1915 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
1917 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
1918 would not have their final values at the moment
1919 <command>gmake</command> encountered the rule. Alas,
1920 <command>gmake</command> takes a snapshot of their
1921 current values, and wires that snapshot into the rule.
1922 (In contrast, the commands executed when the rule
1923 “fires” are only substituted at the moment
1924 of firing.) So, the rule must follow the definitions
1925 given in the <filename>Makefile</filename> itself.</para>
1929 <para>Unlike pattern rules, ordinary rules cannot be
1930 overriden or replaced by subsequent rules for the same
1931 target (at least, not without an error message).
1932 Including ordinary rules in
1933 <filename>boilerplate.mk</filename> would prevent the
1934 user from writing rules for specific targets in specific
1939 <para>There are a couple of other reasons I've
1940 forgotten, but it doesn't matter too much.</para>
1947 <sect2 id="sec-boiler">
1948 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
1949 <indexterm><primary>boilerplate.mk</primary></indexterm>
1951 <para>If you look at
1952 <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
1953 you will find that it consists of the following sections, each
1954 held in a separate file:</para>
1958 <term><filename>config.mk</filename>
1959 <indexterm><primary>config.mk</primary></indexterm>
1962 <para>is the build configuration file we discussed at
1963 length in <xref linkend="sec-build-config"/>.</para>
1968 <term><filename>paths.mk</filename>
1969 <indexterm><primary>paths.mk</primary></indexterm>
1972 <para>defines <command>make</command> variables for
1973 pathnames and file lists. This file contains code for
1974 automatically compiling lists of source files and deriving
1975 lists of object files from those. The results can be
1976 overriden in the <filename>Makefile</filename>, but in
1977 most cases the automatic setup should do the right
1980 <para>The following variables may be set in the
1981 <filename>Makefile</filename> to affect how the automatic
1982 source file search is done:</para>
1986 <term><literal>ALL_DIRS</literal>
1987 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
1990 <para>Set to a list of directories to search in
1991 addition to the current directory for source
1997 <term><literal>EXCLUDED_SRCS</literal>
1998 <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
2001 <para>Set to a list of source files (relative to the
2002 current directory) to omit from the automatic
2003 search. The source searching machinery is clever
2004 enough to know that if you exclude a source file
2005 from which other sources are derived, then the
2006 derived sources should also be excluded. For
2007 example, if you set <literal>EXCLUDED_SRCS</literal>
2008 to include <filename>Foo.y</filename>, then
2009 <filename>Foo.hs</filename> will also be
2015 <term><literal>EXTRA_SRCS</literal>
2016 <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
2019 <para>Set to a list of extra source files (perhaps
2020 in directories not listed in
2021 <literal>ALL_DIRS</literal>) that should be
2027 <para>The results of the automatic source file search are
2028 placed in the following make variables:</para>
2032 <term><literal>SRCS</literal>
2033 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2036 <para>All source files found, sorted and without
2037 duplicates, including those which might not exist
2038 yet but will be derived from other existing sources.
2039 <literal>SRCS</literal> <emphasis>can</emphasis> be
2040 overriden if necessary, in which case the variables
2041 below will follow suit.</para>
2046 <term><literal>HS_SRCS</literal>
2047 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2050 <para>all Haskell source files in the current
2051 directory, including those derived from other source
2052 files (eg. Happy sources also give rise to Haskell
2058 <term><literal>HS_OBJS</literal>
2059 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2062 <para>Object files derived from
2063 <literal>HS_SRCS</literal>.</para>
2068 <term><literal>HS_IFACES</literal>
2069 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2072 <para>Interface files (<literal>.hi</literal> files)
2073 derived from <literal>HS_SRCS</literal>.</para>
2078 <term><literal>C_SRCS</literal>
2079 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2082 <para>All C source files found.</para>
2087 <term><literal>C_OBJS</literal>
2088 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2091 <para>Object files derived from
2092 <literal>C_SRCS</literal>.</para>
2097 <term><literal>SCRIPT_SRCS</literal>
2098 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2101 <para>All script source files found
2102 (<literal>.lprl</literal> files).</para>
2107 <term><literal>SCRIPT_OBJS</literal>
2108 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2111 <para><quote>object</quote> files derived from
2112 <literal>SCRIPT_SRCS</literal>
2113 (<literal>.prl</literal> files).</para>
2118 <term><literal>HSC_SRCS</literal>
2119 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2122 <para>All <literal>hsc2hs</literal> source files
2123 (<literal>.hsc</literal> files).</para>
2128 <term><literal>HAPPY_SRCS</literal>
2129 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2132 <para>All <literal>happy</literal> source files
2133 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2138 <term><literal>OBJS</literal>
2139 <indexterm><primary>OBJS</primary></indexterm>
2142 <para>the concatenation of
2143 <literal>$(HS_OBJS)</literal>,
2144 <literal>$(C_OBJS)</literal>, and
2145 <literal>$(SCRIPT_OBJS)</literal>.</para>
2150 <para>Any or all of these definitions can easily be
2151 overriden by giving new definitions in your
2152 <filename>Makefile</filename>.</para>
2154 <para>What, exactly, does <filename>paths.mk</filename>
2155 consider a <quote>source file</quote> to be? It's based
2156 on the file's suffix (e.g. <filename>.hs</filename>,
2157 <filename>.lhs</filename>, <filename>.c</filename>,
2158 <filename>.hy</filename>, etc), but this is the kind of
2159 detail that changes, so rather than enumerate the source
2160 suffices here the best thing to do is to look in
2161 <filename>paths.mk</filename>.</para>
2166 <term><filename>opts.mk</filename>
2167 <indexterm><primary>opts.mk</primary></indexterm>
2170 <para>defines <command>make</command> variables for option
2171 strings to pass to each program. For example, it defines
2172 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2173 the option strings to pass to the Haskell compiler. See
2174 <xref linkend="sec-suffix"/>.</para>
2179 <term><filename>suffix.mk</filename>
2180 <indexterm><primary>suffix.mk</primary></indexterm>
2183 <para>defines standard pattern rules—see <xref
2184 linkend="sec-suffix"/>.</para>
2189 <para>Any of the variables and pattern rules defined by the
2190 boilerplate file can easily be overridden in any particular
2191 <filename>Makefile</filename>, because the boilerplate
2192 <literal>include</literal> comes first. Definitions after this
2193 <literal>include</literal> directive simply override the default
2194 ones in <filename>boilerplate.mk</filename>.</para>
2197 <sect2 id="sec-platforms">
2198 <title>Platform settings</title>
2199 <indexterm><primary>Platform settings</primary>
2202 <para>There are three platforms of interest when building GHC:</para>
2206 <term>The <emphasis>build</emphasis> platform</term>
2208 <para>The platform on which we are doing this build.</para>
2213 <term>The <emphasis>host</emphasis> platform</term>
2215 <para>The platform on which these binaries will run.</para>
2220 <term>The <emphasis>target</emphasis> platform</term>
2222 <para>The platform for which this compiler will generate code.</para>
2227 <para>These platforms are set when running the
2228 <literal>configure</literal> script, using the
2229 <option>--build</option>, <option>--host</option>, and
2230 <option>--target</option> options. The <filename>mk/config.mk</filename>
2231 file defines several symbols related to the platform settings (see
2232 <filename>mk/config.mk</filename> for details).</para>
2234 <para>We don't currently support build & host being different, because
2235 the build process creates binaries that are both run during the build,
2236 and also installed.</para>
2238 <para>If host and target are different, then we are building a
2239 cross-compiler. For GHC, this means a compiler
2240 which will generate intermediate .hc files to port to the target
2241 architecture for bootstrapping. The libraries and stage 2 compiler
2242 will be built as HC files for the target system (see <xref
2243 linkend="sec-porting-ghc" /> for details.</para>
2245 <para>More details on when to use BUILD, HOST or TARGET can be found in
2246 the comments in <filename>config.mk</filename>.</para>
2249 <sect2 id="sec-suffix">
2250 <title>Pattern rules and options</title>
2251 <indexterm><primary>Pattern rules</primary></indexterm>
2254 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2255 defines standard <emphasis>pattern rules</emphasis> that say how
2256 to build one kind of file from another, for example, how to
2257 build a <filename>.o</filename> file from a
2258 <filename>.c</filename> file. (GNU <command>make</command>'s
2259 <emphasis>pattern rules</emphasis> are more powerful and easier
2260 to use than Unix <command>make</command>'s <emphasis>suffix
2261 rules</emphasis>.)</para>
2263 <para>Almost all the rules look something like this:</para>
2265 <programlisting>%.o : %.c
2267 $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
2269 <para>Here's how to understand the rule. It says that
2270 <emphasis>something</emphasis><filename>.o</filename> (say
2271 <filename>Foo.o</filename>) can be built from
2272 <emphasis>something</emphasis><filename>.c</filename>
2273 (<filename>Foo.c</filename>), by invoking the C compiler (path
2274 name held in <constant>$(CC)</constant>), passing to it
2275 the options <constant>$(CC_OPTS)</constant> and
2276 the rule's dependent file of the rule
2277 <literal>$<</literal> (<filename>Foo.c</filename> in
2278 this case), and putting the result in the rule's target
2279 <literal>$@</literal> (<filename>Foo.o</filename> in this
2282 <para>Every program is held in a <command>make</command>
2283 variable defined in <filename>mk/config.mk</filename>—look
2284 in <filename>mk/config.mk</filename> for the complete list. One
2285 important one is the Haskell compiler, which is called
2286 <constant>$(HC)</constant>.</para>
2288 <para>Every program's options are are held in a
2289 <command>make</command> variables called
2290 <constant><prog>_OPTS</constant>. the
2291 <constant><prog>_OPTS</constant> variables are
2292 defined in <filename>mk/opts.mk</filename>. Almost all of them
2293 are defined like this:</para>
2295 <programlisting>CC_OPTS = \
2296 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
2298 <para>The four variables from which
2299 <constant>CC_OPTS</constant> is built have the following
2304 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
2306 <para>options passed to all C compilations.</para>
2311 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
2313 <para>options passed to C compilations for way
2314 <literal><way></literal>. For example,
2315 <constant>WAY_mp_CC_OPTS</constant>
2316 gives options to pass to the C compiler when compiling way
2317 <literal>mp</literal>. The variable
2318 <constant>WAY_CC_OPTS</constant> holds
2319 options to pass to the C compiler when compiling the
2320 standard way. (<xref linkend="sec-ways"/> dicusses
2321 multi-way compilation.)</para>
2326 <term><constant><module>_CC_OPTS</constant>:</term>
2328 <para>options to pass to the C compiler that are specific
2329 to module <literal><module></literal>. For example,
2330 <constant>SMap_CC_OPTS</constant> gives the
2331 specific options to pass to the C compiler when compiling
2332 <filename>SMap.c</filename>.</para>
2337 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
2339 <para>extra options to pass to all C compilations. This
2340 is intended for command line use, thus:</para>
2342 <screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
2348 <sect2 id="sec-targets">
2349 <title>The main <filename>mk/target.mk</filename> file</title>
2350 <indexterm><primary>target.mk</primary></indexterm>
2352 <para><filename>target.mk</filename> contains canned rules for
2353 all the standard targets described in <xref
2354 linkend="sec-standard-targets"/>. It is complicated by the fact
2355 that you don't want all of these rules to be active in every
2356 <filename>Makefile</filename>. Rather than have a plethora of
2357 tiny files which you can include selectively, there is a single
2358 file, <filename>target.mk</filename>, which selectively includes
2359 rules based on whether you have defined certain variables in
2360 your <filename>Makefile</filename>. This section explains what
2361 rules you get, what variables control them, and what the rules
2362 do. Hopefully, you will also get enough of an idea of what is
2363 supposed to happen that you can read and understand any weird
2364 special cases yourself.</para>
2368 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
2370 <para>If <constant>HS_PROG</constant> is defined,
2371 you get rules with the following targets:</para>
2375 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
2377 <para>itself. This rule links
2378 <constant>$(OBJS)</constant> with the Haskell
2379 runtime system to get an executable called
2380 <constant>$(HS_PROG)</constant>.</para>
2385 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
2388 <constant>$(HS_PROG)</constant> in
2389 <constant>$(bindir)</constant>.</para>
2398 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
2400 <para>is similar to <constant>HS_PROG</constant>,
2401 except that the link step links
2402 <constant>$(C_OBJS)</constant> with the C
2403 runtime system.</para>
2408 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
2410 <para>is similar to <constant>HS_PROG</constant>,
2411 except that it links
2412 <constant>$(LIB_OBJS)</constant> to make the
2413 library archive <constant>$(LIBRARY)</constant>,
2414 and <literal>install</literal> installs it in
2415 <constant>$(libdir)</constant>.</para>
2420 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
2422 <para>…</para>
2427 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
2429 <para>…</para>
2434 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
2436 <para>If <constant>HS_SRCS</constant> is defined
2437 and non-empty, a rule for the target
2438 <literal>depend</literal> is included, which generates
2439 dependency information for Haskell programs. Similarly
2440 for <constant>C_SRCS</constant>.</para>
2445 <para>All of these rules are “double-colon” rules,
2448 <programlisting>install :: $(HS_PROG)
2449 ...how to install it...</programlisting>
2451 <para>GNU <command>make</command> treats double-colon rules as
2452 separate entities. If there are several double-colon rules for
2453 the same target it takes each in turn and fires it if its
2454 dependencies say to do so. This means that you can, for
2455 example, define both <constant>HS_PROG</constant> and
2456 <constant>LIBRARY</constant>, which will generate two rules for
2457 <literal>install</literal>. When you type <command>gmake
2458 install</command> both rules will be fired, and both the program
2459 and the library will be installed, just as you wanted.</para>
2462 <sect2 id="sec-subdirs">
2463 <title>Recursion</title>
2464 <indexterm><primary>recursion, in makefiles</primary></indexterm>
2465 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
2467 <para>In leaf <filename>Makefile</filename>s the variable
2468 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
2469 is undefined. In non-leaf <filename>Makefile</filename>s,
2470 <constant>SUBDIRS</constant> is set to the list of
2471 sub-directories that contain subordinate
2472 <filename>Makefile</filename>s. <emphasis>It is up to you to
2473 set <constant>SUBDIRS</constant> in the
2474 <filename>Makefile</filename>.</emphasis> There is no automation
2475 here—<constant>SUBDIRS</constant> is too important to
2478 <para>When <constant>SUBDIRS</constant> is defined,
2479 <filename>target.mk</filename> includes a rather neat rule for
2480 the standard targets (<xref linkend="sec-standard-targets"/> that
2481 simply invokes <command>make</command> recursively in each of
2482 the sub-directories.</para>
2484 <para><emphasis>These recursive invocations are guaranteed to
2485 occur in the order in which the list of directories is specified
2486 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
2487 be important. For example, when you say <command>gmake
2488 boot</command> it can be important that the recursive invocation
2489 of <command>make boot</command> is done in one sub-directory
2490 (the include files, say) before another (the source files).
2491 Generally, put the most independent sub-directory first, and the
2492 most dependent last.</para>
2495 <sect2 id="sec-ways">
2496 <title>Way management</title>
2497 <indexterm><primary>way management</primary></indexterm>
2499 <para>We sometimes want to build essentially the same system in
2500 several different “ways”. For example, we want to build GHC's
2501 <literal>Prelude</literal> libraries with and without profiling,
2502 so that there is an appropriately-built library archive to link
2503 with when the user compiles his program. It would be possible
2504 to have a completely separate build tree for each such “way”,
2505 but it would be horribly bureaucratic, especially since often
2506 only parts of the build tree need to be constructed in multiple
2510 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2511 contains some clever magic to allow you to build several
2512 versions of a system; and to control locally how many versions
2513 are built and how they differ. This section explains the
2516 <para>The files for a particular way are distinguished by
2517 munging the suffix. The <quote>normal way</quote> is always
2518 built, and its files have the standard suffices
2519 <filename>.o</filename>, <filename>.hi</filename>, and so on.
2520 In addition, you can build one or more extra ways, each
2521 distinguished by a <emphasis>way tag</emphasis>. The object
2522 files and interface files for one of these extra ways are
2523 distinguished by their suffix. For example, way
2524 <literal>mp</literal> has files
2525 <filename>.mp_o</filename> and
2526 <filename>.mp_hi</filename>. Library archives have their
2527 way tag the other side of the dot, for boring reasons; thus,
2528 <filename>libHS_mp.a</filename>.</para>
2530 <para>A <command>make</command> variable called
2531 <constant>way</constant> holds the current way tag.
2532 <emphasis><constant>way</constant> is only ever set on the
2533 command line of <command>gmake</command></emphasis> (usually in
2534 a recursive invocation of <command>gmake</command> by the
2535 system). It is never set inside a
2536 <filename>Makefile</filename>. So it is a global constant for
2537 any one invocation of <command>gmake</command>. Two other
2538 <command>make</command> variables,
2539 <constant>way_</constant> and
2540 <constant>_way</constant> are immediately derived from
2541 <constant>$(way)</constant> and never altered. If
2542 <constant>way</constant> is not set, then neither are
2543 <constant>way_</constant> and
2544 <constant>_way</constant>, and the invocation of
2545 <command>make</command> will build the <quote>normal
2546 way</quote>. If <constant>way</constant> is set, then the other
2547 two variables are set in sympathy. For example, if
2548 <constant>$(way)</constant> is “<literal>mp</literal>”,
2549 then <constant>way_</constant> is set to
2550 “<literal>mp_</literal>” and
2551 <constant>_way</constant> is set to
2552 “<literal>_mp</literal>”. These three variables are
2553 then used when constructing file names.</para>
2555 <para>So how does <command>make</command> ever get recursively
2556 invoked with <constant>way</constant> set? There are two ways
2557 in which this happens:</para>
2561 <para>For some (but not all) of the standard targets, when
2562 in a leaf sub-directory, <command>make</command> is
2563 recursively invoked for each way tag in
2564 <constant>$(WAYS)</constant>. You set
2565 <constant>WAYS</constant> in the
2566 <filename>Makefile</filename> to the list of way tags you
2567 want these targets built for. The mechanism here is very
2568 much like the recursive invocation of
2569 <command>make</command> in sub-directories (<xref
2570 linkend="sec-subdirs"/>). It is up to you to set
2571 <constant>WAYS</constant> in your
2572 <filename>Makefile</filename>; this is how you control what
2573 ways will get built.</para>
2577 <para>For a useful collection of targets (such as
2578 <filename>libHS_mp.a</filename>,
2579 <filename>Foo.mp_o</filename>) there is a rule which
2580 recursively invokes <command>make</command> to make the
2581 specified target, setting the <constant>way</constant>
2582 variable. So if you say <command>gmake
2583 Foo.mp_o</command> you should see a recursive
2584 invocation <command>gmake Foo.mp_o way=mp</command>,
2585 and <emphasis>in this recursive invocation the pattern rule
2586 for compiling a Haskell file into a <filename>.o</filename>
2587 file will match</emphasis>. The key pattern rules (in
2588 <filename>suffix.mk</filename>) look like this:
2590 <programlisting>%.$(way_)o : %.lhs
2591 $(HC) $(HC_OPTS) $< -o $@</programlisting>
2597 <para>You can invoke <command>make</command> with a
2598 particular <literal>way</literal> setting yourself, in order
2599 to build files related to a particular
2600 <literal>way</literal> in the current directory. eg.
2602 <screen>$ make way=p</screen>
2604 will build files for the profiling way only in the current
2611 <title>When the canned rule isn't right</title>
2613 <para>Sometimes the canned rule just doesn't do the right thing.
2614 For example, in the <literal>nofib</literal> suite we want the
2615 link step to print out timing information. The thing to do here
2616 is <emphasis>not</emphasis> to define
2617 <constant>HS_PROG</constant> or
2618 <constant>C_PROG</constant>, and instead define a special
2619 purpose rule in your own <filename>Makefile</filename>. By
2620 using different variable names you will avoid the canned rules
2621 being included, and conflicting with yours.</para>
2625 <sect1 id="building-docs">
2626 <title>Building the documentation</title>
2628 <sect2 id="pre-supposed-doc-tools">
2629 <title>Tools for building the Documentation</title>
2631 <para>The following additional tools are required if you want to
2632 format the documentation that comes with the
2633 <literal>fptools</literal> projects:</para>
2638 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
2639 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
2642 <para>Much of our documentation is written in DocBook XML, instructions
2643 on installing and configuring the DocBook tools are below.</para>
2649 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
2650 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
2653 <para>A decent TeX distribution is required if you want to
2654 produce printable documentation. We recomment teTeX,
2655 which includes just about everything you need.</para>
2661 <indexterm><primary>Haddock</primary></indexterm>
2664 <para>Haddock is a Haskell documentation tool that we use
2665 for automatically generating documentation from the
2666 library source code. It is an <literal>fptools</literal>
2667 project in itself. To build documentation for the
2668 libraries (<literal>fptools/libraries</literal>) you
2669 should check out and build Haddock in
2670 <literal>fptools/haddock</literal>. Haddock requires GHC
2678 <title>Installing the DocBook tools</title>
2681 <title>Installing the DocBook tools on Linux</title>
2683 <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
2684 you probably have working DocBook tools already installed. The
2685 configure script should detect your setup and you're away.</para>
2687 <para>If you don't have DocBook tools installed, and you are
2688 using a system that can handle RPM packages, you can use <ulink
2689 url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
2690 packages for your system. Search for the packages
2691 <literal>docbook-dtd</literal>,
2692 <literal>docbook-xsl-stylesheets</literal>,
2693 <literal>libxslt</literal>,
2694 <literal>libxml2</literal>,
2695 <literal>fop</literal>,
2696 <literal>xmltex</literal>, and
2697 <literal>dvips</literal>.</para>
2701 <title>Installing DocBook on FreeBSD</title>
2703 <para>On FreeBSD systems, the easiest way to get DocBook up
2704 and running is to install it from the ports tree or a
2705 pre-compiled package (packages are available from your local
2706 FreeBSD mirror site).</para>
2708 <para>To use the ports tree, do this:
2709 <screen>$ cd /usr/ports/textproc/docproj
2710 $ make install</screen>
2711 This installs the FreeBSD documentation project tools, which
2712 includes everything needed to format the GHC
2713 documentation.</para>
2717 <title>Installing from binaries on Windows</title>
2719 <para>Probably the fastest route to a working DocBook environment on
2720 Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
2721 with the complete <literal>Doc</literal> category. If you are using
2722 <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
2723 have to help <command>configure</command> a little bit: Set the
2724 environment variables <envar>XmllintCmd</envar> and
2725 <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
2726 <command>xmllint</command> and <command>xsltproc</command>,
2727 respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
2728 of the directory where the XSL stylesheets are installed,
2729 e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
2732 <para>If you want to build HTML Help, you have to install the
2733 <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
2734 too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
2740 <title>Configuring the DocBook tools</title>
2742 <para>Once the DocBook tools are installed, the configure script
2743 will detect them and set up the build system accordingly. If you
2744 have a system that isn't supported, let us know, and we'll try
2749 <title>Building the documentation</title>
2751 <para>To build documentation in a certain format, you can
2752 say, for example,</para>
2754 <screen>$ make html</screen>
2756 <para>to build HTML documentation below the current directory.
2757 The available formats are: <literal>dvi</literal>,
2758 <literal>ps</literal>, <literal>pdf</literal>,
2759 <literal>html</literal>, and <literal>rtf</literal>. Note that
2760 not all documentation can be built in all of these formats: HTML
2761 documentation is generally supported everywhere, and DocBook
2762 documentation might support the other formats (depending on what
2763 other tools you have installed).</para>
2765 <para>All of these targets are recursive; that is, saying
2766 <literal>make html</literal> will make HTML docs for all the
2767 documents recursively below the current directory.</para>
2769 <para>Because there are many different formats that the DocBook
2770 documentation can be generated in, you have to select which ones
2771 you want by setting the <literal>XMLDocWays</literal> variable
2772 to a list of them. For example, in
2773 <filename>build.mk</filename> you might have a line:</para>
2775 <screen>XMLDocWays = html ps</screen>
2777 <para>This will cause the documentation to be built in the requested
2778 formats as part of the main build (the default is not to build
2779 any documentation at all).</para>
2783 <title>Installing the documentation</title>
2785 <para>To install the documentation, use:</para>
2787 <screen>$ make install-docs</screen>
2789 <para>This will install the documentation into
2790 <literal>$(datadir)</literal> (which defaults to
2791 <literal>$(prefix)/share</literal>). The exception is HTML
2792 documentation, which goes into
2793 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
2795 <para>Note that unless you set <literal>$(XMLDocWays)</literal>
2796 to a list of formats, the <literal>install-docs</literal> target
2797 won't do anything for DocBook XML documentation.</para>
2803 <sect1 id="sec-porting-ghc">
2804 <title>Porting GHC</title>
2806 <para>This section describes how to port GHC to a currenly
2807 unsupported platform. There are two distinct
2808 possibilities:</para>
2812 <para>The hardware architecture for your system is already
2813 supported by GHC, but you're running an OS that isn't
2814 supported (or perhaps has been supported in the past, but
2815 currently isn't). This is the easiest type of porting job,
2816 but it still requires some careful bootstrapping. Proceed to
2817 <xref linkend="sec-booting-from-hc"/>.</para>
2821 <para>Your system's hardware architecture isn't supported by
2822 GHC. This will be a more difficult port (though by comparison
2823 perhaps not as difficult as porting gcc). Proceed to <xref
2824 linkend="unregisterised-porting"/>.</para>
2828 <sect2 id="sec-booting-from-hc">
2829 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
2831 <indexterm><primary>building GHC from .hc files</primary></indexterm>
2832 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
2833 <indexterm><primary>porting GHC</primary></indexterm>
2835 <para>Bootstrapping GHC on a system without GHC already
2836 installed is achieved by taking the intermediate C files (known
2837 as HC files) from another GHC compilation, compiling them using gcc to
2838 get a working GHC.</para>
2840 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
2841 from C. We recommend using GHC 6.0.1 or
2842 later.</emphasis></para>
2844 <para>HC files are platform-dependent, so you have to get a set
2845 that were generated on <emphasis>the same platform</emphasis>. There
2846 may be some supplied on the GHC download page, otherwise you'll have to
2847 compile some up yourself, or start from
2848 <emphasis>unregisterised</emphasis> HC files - see <xref
2849 linkend="unregisterised-porting"/>.</para>
2851 <para>The following steps should result in a working GHC build
2852 with full libraries:</para>
2856 <para>Unpack the HC files on top of a fresh source tree
2857 (make sure the source tree version matches the version of
2858 the HC files <emphasis>exactly</emphasis>!). This will
2859 place matching <filename>.hc</filename> files next to the
2860 corresponding Haskell source (<filename>.hs</filename> or
2861 <filename>.lhs</filename>) in the compiler subdirectory
2862 <filename>ghc/compiler</filename> and in the libraries
2864 <literal>libraries</literal>).</para>
2868 <para>The actual build process is fully automated by the
2869 <filename>hc-build</filename> script located in the
2870 <filename>distrib</filename> directory. If you eventually
2871 want to install GHC into the directory
2872 <replaceable>dir</replaceable>, the following
2873 command will execute the whole build process (it won't
2874 install yet):</para>
2876 <screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
2877 <indexterm><primary>--hc-build</primary></indexterm>
2879 <para>By default, the installation directory is
2880 <filename>/usr/local</filename>. If that is what you want,
2881 you may omit the argument to <filename>hc-build</filename>.
2882 Generally, any option given to <filename>hc-build</filename>
2883 is passed through to the configuration script
2884 <filename>configure</filename>. If
2885 <filename>hc-build</filename> successfully completes the
2886 build process, you can install the resulting system, as
2889 <screen>$ make install</screen>
2894 <sect2 id="unregisterised-porting">
2895 <title>Porting GHC to a new architecture</title>
2897 <para>The first step in porting to a new architecture is to get
2898 an <firstterm>unregisterised</firstterm> build working. An
2899 unregisterised build is one that compiles via vanilla C only.
2900 By contrast, a registerised build uses the following
2901 architecture-specific hacks for speed:</para>
2905 <para>Global register variables: certain abstract machine
2906 <quote>registers</quote> are mapped to real machine
2907 registers, depending on how many machine registers are
2909 <filename>ghc/includes/MachRegs.h</filename>).</para>
2913 <para>Assembly-mangling: when compiling via C, we feed the
2914 assembly generated by gcc though a Perl script known as the
2915 <firstterm>mangler</firstterm> (see
2916 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
2917 mangler rearranges the assembly to support tail-calls and
2918 various other optimisations.</para>
2922 <para>In an unregisterised build, neither of these hacks are
2923 used — the idea is that the C code generated by the
2924 compiler should compile using gcc only. The lack of these
2925 optimisations costs about a factor of two in performance, but
2926 since unregisterised compilation is usually just a step on the
2927 way to a full registerised port, we don't mind too much.</para>
2929 <para>Notes on GHC portability in general: we've tried to stick
2930 to writing portable code in most parts of the system, so it
2931 should compile on any POSIXish system with gcc, but in our
2932 experience most systems differ from the standards in one way or
2933 another. Deal with any problems as they arise - if you get
2934 stuck, ask the experts on
2935 <email>glasgow-haskell-users@haskell.org</email>.</para>
2937 <para>Lots of useful information about the innards of GHC is
2938 available in the <ulink
2939 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
2940 Commentary</ulink>, which might be helpful if you run into some
2941 code which needs tweaking for your system.</para>
2944 <title>Cross-compiling to produce an unregisterised GHC</title>
2946 <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
2947 later. If you need instructions for an earlier version of GHC, try
2948 to get hold of the version of this document that was current at the
2949 time. It should be available from the appropriate download page on
2951 url="http://www.haskell.org/ghc/">GHC homepage</ulink>.</para>
2953 <para>In this section, we explain how to bootstrap GHC on a
2954 new platform, using unregisterised intermediate C files. We
2955 haven't put a great deal of effort into automating this
2956 process, for two reasons: it is done very rarely, and the
2957 process usually requires human intervention to cope with minor
2958 porting issues anyway.</para>
2960 <para>The following step-by-step instructions should result in
2961 a fully working, albeit unregisterised, GHC. Firstly, you
2962 need a machine that already has a working GHC (we'll call this
2963 the <firstterm>host</firstterm> machine), in order to
2964 cross-compile the intermediate C files that we will use to
2965 bootstrap the compiler on the <firstterm>target</firstterm>
2970 <para>On the target machine:</para>
2974 <para>Unpack a source tree (preferably a released
2975 version). We will call the path to the root of this
2976 tree <replaceable>T</replaceable>.</para>
2980 <screen>$ cd <replaceable>T</replaceable>
2981 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
2983 <para>You might need to update
2984 <filename>configure.in</filename> to recognise the new
2985 architecture, and re-generate
2986 <filename>configure</filename> with
2987 <literal>autoreconf</literal>.</para>
2991 <screen>$ cd <replaceable>T</replaceable>/ghc/includes
2998 <para>On the host machine:</para>
3002 <para>Unpack a source tree (same released version). Call
3003 this directory <replaceable>H</replaceable>.</para>
3007 <screen>$ cd <replaceable>H</replaceable>
3008 $ ./configure</screen>
3013 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3014 with the following contents:</para>
3016 <programlisting>GhcUnregisterised = YES
3017 GhcLibHcOpts = -O -fvia-C -keep-hc-files
3018 GhcRtsHcOpts = -keep-hc-files
3021 GhcWithNativeCodeGen = NO
3022 GhcWithInterpreter = NO
3023 GhcStage1HcOpts = -O
3024 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3025 SRC_HC_OPTS += -H32m
3026 GhcBootLibs = YES</programlisting>
3031 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3034 <para>change <literal>TARGETPLATFORM</literal>
3035 appropriately, and set the variables involving
3036 <literal>TARGET</literal> to the correct values for
3037 the target platform. This step is necessary because
3038 currently <literal>configure</literal> doesn't cope
3039 with specifying different values for the
3040 <literal>--host</literal> and
3041 <literal>--target</literal> flags.</para>
3044 <para>copy <literal>LeadingUnderscore</literal>
3045 setting from target.</para>
3052 <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>
3054 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3055 Note that we are building on the host machine, using the
3056 target machine's configuration files. This
3057 is so that the intermediate C files generated here will
3058 be suitable for compiling on the target system.</para>
3062 <para>Touch the generated configuration files, just to make
3063 sure they don't get replaced during the build:</para>
3064 <screen>$ cd <filename><replaceable>H</replaceable></filename>/ghc/includes
3065 $ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
3066 $ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
3068 <para>Note: it has been reported that these files still get
3069 overwritten during the next stage. We have installed a fix
3070 for this in GHC 6.4.2, but if you are building a version
3071 before that you need to watch out for these files getting
3072 overwritte by the <literal>Makefile</literal> in
3073 <literal>ghc/includes</literal>. If your system supports
3074 it, you might be able to prevent it by making them
3076 <screen>$ chflags uchg ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h}</screen>
3080 <para>Now build the compiler:</para>
3081 <screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3082 $ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
3083 <para>Don't worry if the build falls over in the RTS, we
3084 don't need the RTS yet.</para>
3088 <screen>$ cd <replaceable>H</replaceable>/libraries
3089 $ make boot && make</screen>
3093 <screen>$ cd <replaceable>H</replaceable>/ghc/compiler
3094 $ make boot stage=2 && make stage=2</screen>
3098 <screen>$ cd <replaceable>H</replaceable>/ghc/lib/compat
3101 $ make boot UseStage1=YES
3102 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3103 $ cd <replaceable>H</replaceable>/ghc/utils
3105 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
3109 <screen>$ cd <replaceable>H</replaceable>
3110 $ make hc-file-bundle Project=Ghc</screen>
3115 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3116 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3122 <para>On the target machine:</para>
3124 <para>At this stage we simply need to bootstrap a compiler
3125 from the intermediate C files we generated above. The
3126 process of bootstrapping from C files is automated by the
3127 script in <literal>distrib/hc-build</literal>, and is
3128 described in <xref linkend="sec-booting-from-hc"/>.</para>
3130 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
3132 <para>However, since this is a bootstrap on a new machine,
3133 the automated process might not run to completion the
3134 first time. For that reason, you might want to treat the
3135 <literal>hc-build</literal> script as a list of
3136 instructions to follow, rather than as a fully automated
3137 script. This way you'll be able to restart the process
3138 part-way through if you need to fix anything on the
3141 <para>Don't bother with running
3142 <literal>make install</literal> in the newly
3143 bootstrapped tree; just use the compiler in that tree to
3144 build a fresh compiler from scratch, this time without
3145 booting from C files. Before doing this, you might want
3146 to check that the bootstrapped compiler is generating
3147 working binaries:</para>
3149 <screen>$ cat >hello.hs
3150 main = putStrLn "Hello World!\n"
3152 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3154 Hello World!</screen>
3156 <para>Once you have the unregisterised compiler up and
3157 running, you can use it to start a registerised port. The
3158 following sections describe the various parts of the
3159 system that will need architecture-specific tweaks in
3160 order to get a registerised build going.</para>
3167 <title>Porting the RTS</title>
3169 <para>The following files need architecture-specific code for a
3170 registerised build:</para>
3174 <term><filename>ghc/includes/MachRegs.h</filename>
3175 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
3178 <para>Defines the STG-register to machine-register
3179 mapping. You need to know your platform's C calling
3180 convention, and which registers are generally available
3181 for mapping to global register variables. There are
3182 plenty of useful comments in this file.</para>
3186 <term><filename>ghc/includes/TailCalls.h</filename>
3187 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
3190 <para>Macros that cooperate with the mangler (see <xref
3191 linkend="sec-mangler"/>) to make proper tail-calls
3196 <term><filename>ghc/rts/Adjustor.c</filename>
3197 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
3201 <literal>foreign import "wrapper"</literal>
3203 <literal>foreign export dynamic</literal>).
3204 Not essential for getting GHC bootstrapped, so this file
3205 can be deferred until later if necessary.</para>
3209 <term><filename>ghc/rts/StgCRun.c</filename>
3210 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
3213 <para>The little assembly layer between the C world and
3214 the Haskell world. See the comments and code for the
3215 other architectures in this file for pointers.</para>
3219 <term><filename>ghc/rts/MBlock.h</filename>
3220 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
3222 <term><filename>ghc/rts/MBlock.c</filename>
3223 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
3226 <para>These files are really OS-specific rather than
3227 architecture-specific. In <filename>MBlock.h</filename>
3228 is specified the absolute location at which the RTS
3229 should try to allocate memory on your platform (try to
3230 find an area which doesn't conflict with code or dynamic
3231 libraries). In <filename>Mblock.c</filename> you might
3232 need to tweak the call to <literal>mmap()</literal> for
3239 <sect3 id="sec-mangler">
3240 <title>The mangler</title>
3242 <para>The mangler is an evil Perl-script
3243 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
3244 rearranges the assembly code output from gcc to do two main
3249 <para>Remove function prologues and epilogues, and all
3250 movement of the C stack pointer. This is to support
3251 tail-calls: every code block in Haskell code ends in an
3252 explicit jump, so we don't want the C-stack overflowing
3253 while we're jumping around between code blocks.</para>
3256 <para>Move the <firstterm>info table</firstterm> for a
3257 closure next to the entry code for that closure. In
3258 unregisterised code, info tables contain a pointer to the
3259 entry code, but in registerised compilation we arrange
3260 that the info table is shoved right up against the entry
3261 code, and addressed backwards from the entry code pointer
3262 (this saves a word in the info table and an extra
3263 indirection when jumping to the closure entry
3268 <para>The mangler is abstracted to a certain extent over some
3269 architecture-specific things such as the particular assembler
3270 directives used to herald symbols. Take a look at the
3271 definitions for other architectures and use these as a
3272 starting point.</para>
3276 <title>The splitter</title>
3278 <para>The splitter is another evil Perl script
3279 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
3280 cooperates with the mangler to support object splitting.
3281 Object splitting is what happens when the
3282 <option>-split-objs</option> option is passed to GHC: the
3283 object file is split into many smaller objects. This feature
3284 is used when building libraries, so that a program statically
3285 linked against the library will pull in less of the
3288 <para>The splitter has some platform-specific stuff; take a
3289 look and tweak it for your system.</para>
3293 <title>The native code generator</title>
3295 <para>The native code generator isn't essential to getting a
3296 registerised build going, but it's a desirable thing to have
3297 because it can cut compilation times in half. The native code
3298 generator is described in some detail in the <ulink
3299 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3300 commentary</ulink>.</para>
3306 <para>To support GHCi, you need to port the dynamic linker
3307 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
3308 currently supports the ELF and PEi386 object file formats - if
3309 your platform uses one of these then things will be
3310 significantly easier. The majority of Unix platforms use the
3311 ELF format these days. Even so, there are some
3312 machine-specific parts of the ELF linker: for example, the
3313 code for resolving particular relocation types is
3314 machine-specific, so some porting of this code to your
3315 architecture will probaly be necessary.</para>
3317 <para>If your system uses a different object file format, then
3318 you have to write a linker — good luck!</para>
3324 <sect1 id="sec-build-pitfalls">
3325 <title>Known pitfalls in building Glasgow Haskell
3327 <indexterm><primary>problems, building</primary></indexterm>
3328 <indexterm><primary>pitfalls, in building</primary></indexterm>
3329 <indexterm><primary>building pitfalls</primary></indexterm></title>
3332 WARNINGS about pitfalls and known “problems”:
3341 One difficulty that comes up from time to time is running out of space
3342 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
3343 compensate for the vagaries of different sysadmin approaches to temp
3345 <indexterm><primary>tmp, running out of space in</primary></indexterm>
3347 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
3348 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
3351 The best way around it is to say
3353 <programlisting>export TMPDIR=<dir></programlisting>
3355 in your <filename>build.mk</filename> file.
3356 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
3365 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
3366 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
3374 When compiling via C, you'll sometimes get “warning: assignment from
3375 incompatible pointer type” out of GCC. Harmless.
3382 Similarly, <command>ar</command>chiving warning messages like the following are not
3385 <screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
3386 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
3395 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
3396 get an “Out of heap space” error message. These can vary with the
3397 vagaries of different systems, it seems. The solution is simple:
3404 If you're compiling with GHC 4.00 or later, then the
3405 <emphasis>maximum</emphasis> heap size must have been reached. This
3406 is somewhat unlikely, since the maximum is set to 64M by default.
3407 Anyway, you can raise it with the
3408 <option>-optCrts-M<size></option> flag (add this flag to
3409 <constant><module>_HC_OPTS</constant>
3410 <command>make</command> variable in the appropriate
3411 <filename>Makefile</filename>).
3418 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
3427 and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
3428 <constant><module>_HC_OPTS</constant>.)
3430 Alternatively, just cut to the chase:
3432 <screen>$ cd ghc/compiler
3433 $ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
3441 If you try to compile some Haskell, and you get errors from GCC about
3442 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
3443 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
3445 As <command>fixincludes</command> is now automagically run as part of GCC installation,
3446 this bug also suggests that you have an old GCC.
3454 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
3457 <screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
3458 $ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
3460 ? # or, on some machines: ar s $i
3464 We'd be interested to know if this is still necessary.
3472 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
3473 a bit from one Unix to another. One particular gotcha is macro calls
3477 <programlisting>SLIT("Hello, world")</programlisting>
3480 Some <command>cpp</command>s treat the comma inside the string as separating two macro
3481 arguments, so you get
3484 <screen>:731: macro `SLIT' used with too many (2) args</screen>
3487 Alas, <command>cpp</command> doesn't tell you the offending file!
3489 Workaround: don't put weird things in string args to <command>cpp</command> macros.
3500 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
3502 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
3503 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
3506 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
3508 <para> The build system is built around Unix-y makefiles. Because it's not native,
3509 the Windows situation for building GHC is particularly confusing. This section
3510 tries to clarify, and to establish terminology.</para>
3512 <sect3 id="ghc-mingw"><title>MinGW</title>
3514 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
3515 is a collection of header
3516 files and import libraries that allow one to use <command>gcc</command> and produce
3517 native Win32 programs that do not rely on any third-party DLLs. The
3518 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
3519 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
3523 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
3528 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
3530 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
3531 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
3532 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</command>.
3533 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
3534 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
3538 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
3539 compile code that has access to all of Posix. The price is that the executables must be
3540 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
3541 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
3542 does not change, but the implementation certainly does. Even the interfaces to functions
3543 it exports seem to change occasionally. </para>
3547 MSYS is a fork of the Cygwin tree, so they
3548 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
3549 through fewer layers, so MSYS is quite a bit faster too.
3552 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
3553 compile binaries that run with no DLL support, on any Win32 system.
3554 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
3555 <command>darcs</command>, <command>ssh</command> etc. To get these, you have to download the
3556 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
3558 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
3559 <command>ssh</command> and so on),
3560 not by programs compiled under MSYS.
3568 <sect3><title>Targeting MinGW</title>
3570 <para>We want GHC to compile programs that work on any Win32 system. Hence:
3573 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
3574 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
3575 will work on any system, but it also means that the programs GHC compiles do not have access
3576 to all of Posix. In particular, they cannot import the (Haskell) Posix
3577 library; they have to do
3578 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
3579 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
3583 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
3584 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
3587 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
3588 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
3589 that targets Cygwin instead. The up-side of GHC-cygwin is
3590 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
3591 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
3594 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
3595 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
3596 GHC; both work fine, though MSYS is rather lighter weight.</para>
3598 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
3599 uses the <command>gcc</command> that you specify using the
3600 <option>--with-gcc</option> flag when you run
3601 <command>configure</command> (see below).
3602 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
3603 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
3604 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
3605 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
3606 used to glom together .o files into a bigger .o file, or a .a file,
3607 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
3608 Cygwin and MinGW use the same .o file format. So its ok.
3612 <sect3><title> File names </title>
3614 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
3618 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
3619 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
3621 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
3622 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
3623 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
3625 <programlisting>foogle -B/c/tmp/baz</programlisting>
3626 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
3630 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
3632 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
3638 <sect3><title>Crippled <command>ld</command></title>
3641 It turns out that on both Cygwin and MSYS, the <command>ld</command> has a
3642 limit of 32kbytes on its command line. Especially when using split object
3643 files, the make system can emit calls to <command>ld</command> with thousands
3644 of files on it. Then you may see something like this:
3646 (cd Graphics/Rendering/OpenGL/GL/QueryUtils_split && /mingw/bin/ld -r -x -o ../QueryUtils.o *.o)
3647 /bin/sh: /mingw/bin/ld: Invalid argument
3649 The solution is either to switch off object file splitting (set
3650 <option>SplitObjs</option> to <literal>NO</literal> in your
3651 <filename>build.mk</filename>),
3652 or to make the module smaller.
3656 <sect3><title>Host System vs Target System</title>
3659 In the source code you'll find various ifdefs looking like:
3660 <programlisting>#ifdef mingw32_HOST_OS
3662 #endif</programlisting>
3664 <programlisting>#ifdef mingw32_TARGET_OS
3666 #endif</programlisting>
3667 These macros are set by the configure script (via the file config.h).
3668 Which is which? The criterion is this. In the ifdefs in GHC's source code:
3671 <para>The "host" system is the one on which GHC itself will be run.</para>
3674 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
3677 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
3678 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
3685 <sect2><title>Wrapper scripts</title>
3688 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
3689 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
3690 GHC itself as an example:
3693 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
3694 paths to the front of the source file <filename>ghc.sh</filename>,
3695 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
3696 where to find its supporting files.
3700 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
3701 native Windows shell <command>cmd</command> (e.g. limits on the length
3702 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
3703 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
3704 and from that figures out where the supporting files are.
3707 (You can find the layout of GHC's supporting files in the
3708 section "Layout of installed files" of Section 2 of the GHC user guide.)
3711 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
3712 execute a program that has just been built in a build tree. The difference is that the
3713 layout of the supporting files is different.
3714 In this case, whether on Windows or Unix, we always use a shell script. This works OK
3715 on Windows because the script is executed by MSYS or Cygwin, which don't have the
3716 shortcomings of the native Windows <command>cmd</command> shell.
3723 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
3726 This section gives detailed instructions for how to build
3727 GHC from source on your Windows machine. Similar instructions for
3728 installing and running GHC may be found in the user guide. In general,
3729 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
3732 Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
3733 before reading section.
3734 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
3735 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
3738 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
3741 MSYS is a lightweight alternative to Cygwin.
3742 You don't need MSYS to <emphasis>use</emphasis> GHC,
3743 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
3744 Here's how to install MSYS.
3747 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
3748 download the following (of course, the version numbers will differ):
3750 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
3752 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
3753 This provides <command>make</command>, <command>autoconf</command>,
3754 <command>ssh</command> and probably more besides.
3757 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
3761 Set the following environment variables
3763 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> and
3764 <literal>c:/msys/1.0/local/bin</literal>
3765 to your path. (Of course, the version number may differ.)
3766 MSYS mounts the former as both <literal>/bin</literal> and
3767 <literal>/usr/bin</literal> and the latter as <literal>/usr/local/bin</literal>.
3770 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
3771 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
3774 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
3777 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
3781 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
3788 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
3789 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
3790 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
3791 file has too-liberal permissinos.
3796 <para>Here are some points to bear in mind when using MSYS:
3798 <listitem> <para> MSYS does some kind of special magic to binaries stored in
3799 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
3800 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
3801 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
3802 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
3803 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
3805 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
3809 Win32 has a <command>find</command> command which is not the same as MSYS's find.
3810 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
3811 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
3812 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
3813 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
3817 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
3818 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
3819 bzip'd dump.</para></listitem>
3825 <sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title>
3827 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
3828 The installation process is straightforward; we install it in
3829 <filename>c:/cygwin</filename>.</para>
3831 You must install enough Cygwin <emphasis>packages</emphasis> to support
3832 building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this:
3834 <listitem><para>The direct, but laborious way is to
3835 select all of the following packages in the installation dialogue:
3836 <command>cvs</command>,
3837 <command>openssh</command>,
3838 <command>autoconf</command>,
3839 <command>binutils</command> (includes ld and (I think) ar),
3840 <command>gcc</command>,
3841 <command>flex</command>,
3842 <command>make</command>.
3843 To see thse packages,
3844 click on the "View" button in the "Select Packages"
3845 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
3846 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
3850 <listitem><para>The clever way is to point the Cygwin installer at the
3851 <command>ghc-depends</command> package, which is kept at <ulink
3852 url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
3853 When the Cygwin installer asks you to "Choose a Download Site", choose one of
3855 offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
3856 "User URL" box and click "Add"; now two sites are selected. (The Cygwin
3857 installer remembers this for next time.)
3858 Click "Next".</para>
3859 <para>In the "Select Packages" dialogue box that follows, click the "+" sign by
3860 "Devel", scroll down to the end of the "Devel" packages, and choose
3861 <command>ghc-depends</command>.
3862 The package <command>ghc-depends</command> will not actually install anything itself,
3863 but forces additional packages to be added by the Cygwin installer.
3869 <para> Now set the following user environment variables:
3872 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
3873 <constant>PATH</constant></para></listitem>
3877 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
3878 don't do this you get very weird messages when you type
3879 <command>make</command>, such as:
3880 <screen>/c: /c: No such file or directory</screen>
3884 <listitem><para> Set <constant>SHELL</constant> to
3885 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
3886 <constant>SHELL</constant> is what you get.
3889 <listitem><para> Set <constant>HOME</constant> to point to your
3890 home directory. This is where, for example,
3891 <command>bash</command> will look for your <filename>.bashrc</filename>
3892 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
3897 <para>Here are some things to be aware of when using Cygwin:
3899 <listitem> <para>Cygwin doesn't deal well with filenames that include
3900 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
3904 <listitem> <para> Cygwin implements a symbolic link as a text file with some
3905 magical text in it. So other programs that don't use Cygwin's
3906 I/O libraries won't recognise such files as symlinks.
3907 In particular, programs compiled by GHC are meant to be runnable
3908 without having Cygwin, so they don't use the Cygwin library, so
3909 they don't recognise symlinks.
3913 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
3914 which apply to Cygwin too.
3919 Some script files used in the make system start with "<command>#!/bin/perl</command>",
3920 (and similarly for <command>sh</command>). Notice the hardwired path!
3921 So you need to ensure that your <filename>/bin</filename> directory has at least
3922 <command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
3923 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
3924 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
3925 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
3926 (You can discover where your Cygwin
3927 root directory <filename>/</filename> is by typing <command>mount</command>.)
3928 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
3929 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
3930 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
3936 By default, cygwin provides the command shell <filename>ash</filename>
3937 as <filename>sh.exe</filename>. It seems to be fine now, but in the past we
3938 saw build-system problems that turned out to be due to bugs in <filename>ash</filename>
3939 (to do with quoting and length of command lines). On the other hand <filename>bash</filename> seems
3941 If this happens to you (which it shouldn't), in <filename>cygwin/bin</filename>
3942 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
3943 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
3944 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
3945 you can't rename a running program!
3954 <sect2 id="configure-ssh"><title>Configuring SSH</title>
3956 <para><command>ssh</command> comes with both Cygwin and MSYS.
3957 (Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
3958 in the Cygwin list of packages; or use the <command>ghc-depends</command>
3959 package -- see <xref linkend="install-cygwin"/>.)</para>
3961 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
3965 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
3966 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
3967 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
3968 and run it as follows:
3969 <screen>c:\tmp> set CYGWIN32=tty
3970 c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
3973 <listitem><para> (Cygwin-only problem, I think.)
3974 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
3975 To determine your home directory <command>ssh</command> first looks in
3976 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
3977 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
3978 the setting of the environment variable $HOME</emphasis>. If the home directory is
3979 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
3980 <screen>ssh -v cvs.haskell.org</screen>
3981 which makes <command>ssh</command> print out information about its activity.
3983 <para> You can fix this problem, either by correcting the home-directory field in
3984 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
3985 you do that, <command>ssh</command> uses the $HOME environment variable instead.
3991 <para>To protect your
3992 <literal>.ssh</literal> from access by anyone else,
3993 right-click your <literal>.ssh</literal> directory, and
3994 select <literal>Properties</literal>. If you are not on
3995 the access control list, add yourself, and give yourself
3996 full permissions (the second panel). Remove everyone else
3997 from the access control list. Don't leave them there but
3998 deny them access, because 'they' may be a list that
3999 includes you!</para>
4003 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4004 you to have Unix permissions 600 (read/write for owner only)
4005 on the <literal>.ssh/identity</literal> file, else it
4006 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4007 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4008 The solution seems to be to set the $CYGWIN environment
4009 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4010 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4011 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4018 <sect2><title>Other things you need to install</title>
4020 <para>You have to install the following other things to build GHC, listed below.</para>
4022 <para>On Windows you often install executables in directories with spaces, such as
4023 "<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
4024 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
4025 to put binaries for all tools in places with no spaces in their path.
4026 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
4027 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
4028 provided they are in your path.
4032 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4033 This is what you will use to compile GHC. Add it in your
4034 <constant>PATH</constant>: the installer tells you the path element
4035 you need to add upon completion.
4041 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4042 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
4043 build it from the source distribution using
4044 <screen>$ ./configure
4046 $ make install</screen>
4047 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
4049 Make sure the installation directory is in your
4050 <constant>PATH</constant>.
4055 <para>Install an executable Alex. This can be done by building from the
4056 source distribution in the same way as Happy. Sources are
4057 available from <ulink
4058 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4062 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4063 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
4064 Just pick up a mingw bundle at
4065 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4066 We install it in <filename>c:/mingw</filename>.
4069 <para><emphasis>On MSYS</emphasis>, add <literal>c:/mingw/bin</literal> to your PATH. MSYS does not provide <command>gcc</command>,
4070 <command>ld</command>, <command>ar</command>, and so on, because it just uses the MinGW ones. So you need them
4074 <para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4075 They are only going to get used by explicit access (via the --with-gcc flag you
4076 give to <command>configure</command> later). If you do add them to your path
4077 you are likely to get into a mess because their names overlap with Cygwin
4079 On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
4080 (and perhaps one or two other things) in your path. The Cygwin ones are fine,
4081 but you must have them; hence needing the Cygwin binutils package.
4087 <para>We use <command>emacs</command> a lot, so we install that too.
4088 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4089 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4090 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4091 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4092 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4093 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4098 <para>You might want to install GLUT in your MSYS/Cygwin
4099 installation, otherwise the GLUT package will not be built with
4104 <para> Finally, check out a copy of GHC sources from
4105 the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para>
4111 <sect2><title>Building GHC</title>
4114 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
4115 the bullets below only tell
4116 you about Windows-specific wrinkles.</para>
4120 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
4121 you'll get an error when you run <filename>./configure</filename>:
4124 creating mk/config.h
4125 mk/config.h is unchanged
4127 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4128 ./configure: ./configure: No such file or directory
4129 configure: error: ./configure failed for ghc</screen>
4133 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
4134 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
4136 <screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
4137 Solution: delete <filename>configure</filename> first.
4142 After <command>autoreconf</command> run <command>./configure</command> in
4143 <filename>fptools/</filename> thus:
4145 <screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
4146 This is the point at which you specify that you are building GHC-mingw
4147 (see <xref linkend="ghc-mingw"/>). </para>
4149 <para> Both these options are important! It's possible to get into
4150 trouble using the wrong C compiler!</para>
4152 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4153 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4154 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4155 understand a Cygwin path. For example, if you
4156 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4157 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4158 time it tries to invoke it. Worse, the failure comes with
4159 no error message whatsoever. GHC simply fails silently when first invoked,
4160 typically leaving you with this:
4161 <screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4162 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4163 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4164 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4165 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4166 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4167 -optc-fomit-frame-pointer -O2 -static
4168 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4169 make[2]: *** [Adjustor.o] Error 1
4170 make[1]: *** [all] Error 1
4171 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4172 make: *** [all] Error 1</screen>
4177 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
4178 you'll have to do something more like:
4179 <screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
4184 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4185 This file occasionally remembers out-of-date configuration information, which
4186 can be really confusing.
4190 <listitem><para> You almost certainly want to set
4191 <programlisting>SplitObjs = NO</programlisting>
4192 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
4193 This tells the build system not to split each library into a myriad of little object files, one
4194 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4195 it dramatically increases the time taken to build the libraries in the first place.
4199 <listitem><para> Do not attempt to build the documentation.
4200 It needs all kinds of wierd Jade stuff that we haven't worked out for
4201 Win32.</para></listitem>
4206 <sect2><title>A Windows build log using Cygwin</title>
4208 <para>Here is a complete, from-scratch, log of all you need to build GHC using
4209 Cygwin, kindly provided by Claus Reinke. It does not discuss alternative
4210 choices, but it gives a single path that works.</para>
4211 <programlisting>- Install some editor (vim, emacs, whatever)
4213 - Install cygwin (http://www.cygwin.com)
4214 ; i used 1.5.16-1, installed in c:\cygwin
4216 Choose a Download Source:
4217 select 'download from internet';
4218 Select Root Install Directory:
4219 root dir: c:\cygwin;
4220 install for: all users;
4221 default file type: unix
4222 Select Local Package Directory
4223 choose a spare temporary home
4224 Select Your Internet Connection
4226 Choose a Download Site
4227 Choose your preferred main mirror and
4228 Add 'http://www.haskell.org/ghc/cygwin'
4230 In addition to 'Base' (default install),
4231 select 'Devel->ghc-depends'
4233 - Install mingw (http://www.mingw.org/)
4234 ; i used MinGW-3.1.0-1.exe
4235 ; installed in c:\mingw
4236 - you probably want to add GLUT
4237 ; (http://www.xmission.com/~nate/glut.html)
4238 ; i used glut-3.7.3-mingw32.tar
4240 - Get recent binary snapshot of ghc-6.4.1 for mingw
4241 ; (http://www.haskell.org/ghc/dist/stable/dist/)
4243 - add C:\ghc\ghc-6.4.1\bin to %PATH%
4244 (Start->Control Panel->System->Advanced->Environment Variables)
4246 - Get darcs version of ghc
4247 ; also, subscribe to cvs-all@haskell.org, or follow the mailing list
4248 ; archive, in case you checkout a version with problems
4249 ; http://www.haskell.org//pipermail/cvs-all/
4250 - mkdir c:/fptools; cd c:/fptools
4251 ; (or whereever you want your darcs tree to be)
4252 - darcs get http://darcs.haskell.org/ghc
4254 - chmod +x darcs-all
4257 - Build ghc, using cygwin and mingw, targetting mingw
4258 - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
4259 ; for haddock, alex, happy (*)
4260 - export PATH=/cygdrive/c/mingw/bin:$PATH
4261 ; without, we pick up some cygwin tools at best!
4262 - cd c:/fptools/fptools
4263 ; (if you aren't there already)
4265 - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
4266 ; we use cygwin, but build for windows
4267 - cp mk/build.mk.sample mk/build.mk
4269 add line: SplitObjs = NO
4270 (MSYS seems slow when there are zillions of object files)
4271 uncomment line: BuildFlavour = perf
4272 (or BuildFlavour = devel, if you are doing development)
4273 add line: BIN_DIST=1
4274 - make 2>&1 | tee make.log
4275 ; always useful to have a log around
4277 - Package up binary distribution
4278 - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log
4279 ; always useful to have a log around
4281 - chmod +x ../distrib/prep-bin-dist-mingw
4282 ; if you're happy with the script's contents (*)
4283 - ../distrib/prep-bin-dist-mingw
4284 ; then tar up, unpack where wanted, and enjoy</programlisting>
projects / ghc-hetmet.git / blob