1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
3 <Article id="building-guide">
7 <Title>Building the Glasgow Functional Programming Tools Suite</Title>
8 <Author><OtherName>The GHC Team</OtherName></Author>
9 <Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
10 <PubDate>November 2001</PubDate>
13 <para>The Glasgow fptools suite is a collection of Functional
14 Programming related tools, including the Glasgow Haskell
15 Compiler (GHC). The source code for the whole suite is kept in
16 a single CVS repository and shares a common build and
17 installation system.</para>
19 <para>This guide is intended for people who want to build or
20 modify programs from the Glasgow <Literal>fptools</Literal>
21 suite (as distinct from those who merely want to
22 <Emphasis>run</Emphasis> them). Installation instructions are
23 now provided in the user guide.</para>
25 <para>The bulk of this guide applies to building on Unix
26 systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
32 <sect1 id="sec-getting">
33 <title>Getting the sources</title>
35 <para>You can get your hands on the <literal>fptools</literal>
41 <term><indexterm><primary>Source
42 distributions</primary></indexterm>Source distributions</term>
44 <para>You have a supported platform, but (a) you like
45 the warm fuzzy feeling of compiling things yourself;
46 (b) you want to build something ``extra”—e.g., a
47 set of libraries with strictness-analysis turned off; or
48 (c) you want to hack on GHC yourself.</para>
50 <para>A source distribution contains complete sources for
51 one or more projects in the <literal>fptools</literal>
52 suite. Not only that, but the more awkward
53 machine-independent steps are done for you. For example, if
55 <command>happy</command><indexterm><primary>happy</primary></indexterm>
56 you'll find it convenient that the source distribution
57 contains the result of running <command>happy</command> on
58 the parser specifications. If you don't want to alter the
59 parser then this saves you having to find and install
60 <command>happy</command>. You will still need a working
61 version of GHC (preferably version 4.08+) on your machine in
62 order to compile (most of) the sources, however.</para>
67 <term>The CVS repository.</term>
68 <indexterm><primary>CVS repository</primary>
71 <para>We make releases infrequently. If you want more
72 up-to-the minute (but less tested) source code then you need
73 to get access to our CVS repository.</para>
75 <para>All the <literal>fptools</literal> source code is held
76 in a CVS repository. CVS is a pretty good source-code
77 control system, and best of all it works over the
80 <para>The repository holds source code only. It holds no
81 mechanically generated files at all. So if you check out a
82 source tree from CVS you will need to install every utility
83 so that you can build all the derived files from
86 <para>More information about our CVS repository can be found
87 in <xref linkend="sec-cvs">.</para>
92 <para>If you are going to do any building from sources (either
93 from a source distribution or the CVS repository) then you need to
94 read all of this manual in detail.</para>
98 <title>Using the CVS repository</title>
100 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
101 sources for various software projects. CVS lets several people
102 work on the same software at the same time, allowing changes to be
103 checked in incrementally. </para>
105 <para>This section is a set of guidelines for how to use our CVS
106 repository, and will probably evolve in time. The main thing to
107 remember is that most mistakes can be undone, but if there's
108 anything you're not sure about feel free to bug the local CVS
109 meister (namely Jeff Lewis
110 <email>jlewis@galconn.com</email>). </para>
112 <sect2 id="cvs-access">
113 <title>Getting access to the CVS Repository</title>
115 <para>You can access the repository in one of two ways:
116 read-only (<xref linkend="cvs-read-only">), or read-write (<xref
117 linkend="cvs-read-write">).</para>
119 <sect3 id="cvs-read-only">
120 <title>Remote Read-only CVS Access</title>
122 <para>Read-only access is available to anyone - there's no
123 need to ask us first. With read-only CVS access you can do
124 anything except commit changes to the repository. You can
125 make changes to your local tree, and still use CVS's merge
126 facility to keep your tree up to date, and you can generate
127 patches using 'cvs diff' in order to send to us for
130 <para>To get read-only access to the repository:</para>
134 <para>Make sure that <application>cvs</application> is
135 installed on your machine.</para>
138 <para>Set your <literal>$CVSROOT</literal> environment variable to
139 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
142 <para>Run the command</para>
146 <para>The password is simply <literal>cvs</literal>. This
147 sets up a file in your home directory called
148 <literal>.cvspass</literal>, which squirrels away the
149 dummy password, so you only need to do this step once.</para>
153 <para>Now go to <xref linkend="cvs-first">.</para>
158 <sect3 id="cvs-read-write">
159 <title>Remote Read-Write CVS Access</title>
161 <para>We generally supply read-write access to folk doing
162 serious development on some part of the source tree, when
163 going through us would be a pain. If you're developing some
164 feature, or think you have the time and inclination to fix
165 bugs in our sources, feel free to ask for read-write
166 access. There is a certain amount of responsibility that goes
167 with commit privileges; we are more likely to grant you access
168 if you've demonstrated your competence by sending us patches
169 via mail in the past.</para>
171 <para>To get remote read-write CVS access, you need to do the
172 following steps.</para>
176 <para>Make sure that <literal>cvs</literal> and
177 <literal>ssh</literal> are both installed on your
182 <para>Generate a DSA private-key/public-key pair, thus:</para>
186 <para>(<literal>ssh-keygen</literal> comes with
187 <literal>ssh</literal>.) Running <literal>ssh-keygen
188 -d</literal> creates the private and public keys in
189 <literal>$HOME/.ssh/id_dsa</literal> and
190 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
191 (assuming you accept the standard defaults).</para>
193 <para><literal>ssh-keygen -d</literal> will only work if
194 you have Version 2 <literal>ssh</literal> installed; it
195 will fail harmlessly otherwise. If you only have Version
196 1 you can instead generate an RSA key pair using plain</para>
201 <para>Doing so creates the private and public RSA keys in
202 <literal>$HOME/.ssh/identity</literal> and
203 <literal>$HOME/.ssh/identity.pub</literal>
206 <para>[Deprecated.] Incidentally, you can force a Version
207 2 <literal>ssh</literal> to use the Version 1 protocol by
208 creating <literal>$HOME/config</literal> with the
209 following in it:</para>
217 <para>In both cases, <literal>ssh-keygen</literal> will
218 ask for a <firstterm>passphrase</firstterm>. The
219 passphrase is a password that protects your private key.
220 In response to the 'Enter passphrase' question, you can
224 <para>[Recommended.] Enter a passphrase, which you
225 will quote each time you use CVS.
226 <literal>ssh-agent</literal> makes this entirely
230 <para>[Deprecated.] Just hit return (i.e. use an empty
231 passphrase); then you won't need to quote the
232 passphrase when using CVS. The downside is that
233 anyone who can see into your <literal>.ssh</literal>
234 directory, and thereby get your private key, can mess
235 up the repository. So you must keep the
236 <literal>.ssh</literal> directory with draconian
237 no-access permissions.</para>
243 [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
244 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
245 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
246 and run it as follows:
248 c:\tmp> set CYGWIN32=tty
249 c:\tmp> c:/user/local/bin/ssh-keygen1
252 <para>[Windows users.] To protect your
253 <literal>.ssh</literal> from access by anyone else,
254 right-click your <literal>.ssh</literal> directory, and
255 select <literal>Properties</literal>. If you are not on
256 the access control list, add yourself, and give yourself
257 full permissions (the second panel). Remove everyone else
258 from the access control list. Don't leave them there but
259 deny them access, because 'they' may be a list that
261 <para>[March 2003] In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
262 you to have Unix permissions 600 (read/write for owner only)
263 on the <literal>.ssh/identity</literal> file, else it
264 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
265 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
266 The solution seems to be to set the CYGWIN environment
267 variable to "<literal>ntsec neta</literal>". The CYGWIN environment variable is discussed
268 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
269 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
274 <para>Send a message to to the CVS repository
275 administrator (currently Jeff Lewis
276 <email>jeff@galconn.com</email>), containing:</para>
279 <para>Your desired user-name.</para>
282 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
283 <literal>.ssh/identity.pub</literal>).</para>
286 <para>He will set up your account.</para>
290 <para>Set the following environment variables:</para>
294 <constant>$HOME</constant>: points to your home directory. This is where CVS
295 will look for its <filename>.cvsrc</filename> file.
301 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
303 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
304 <literal>ssh</literal> assumes that your CVS client
305 understands how to execute shell script
306 ("#!"s,really), which is what
307 <literal>ssh</literal> is. This may not be the case on
308 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
309 <literal>ssh1</literal>.</para>
313 <para><literal>$CVSROOT</literal> to
314 <literal>:ext:</literal><replaceable>your-username</replaceable>
315 <literal>@cvs.haskell.org:/home/cvs/root</literal>
316 where <replaceable>your-username</replaceable> is your user name on
317 <literal>cvs.haskell.org</literal>.
319 <para>The <literal>CVSROOT</literal> environment variable will
320 be recorded in the checked-out tree, so you don't need to set
321 this every time. </para>
327 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
328 if you want to use an Emacs buffer for typing in those long commit messages.
334 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
335 set this to point to <filename>bash.exe</filename>.
346 Put the following in <filename>$HOME/.cvsrc</filename>:
357 These are the default options for the specified CVS commands,
358 and represent better defaults than the usual ones. (Feel
359 free to change them.)
363 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
364 the 8.3 DOS filesystem, but that restriction should have
365 been lifted by now (i.e., you're using VFAT or later filesystems.) If
366 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
374 <para>[Experts.] Once your account is set up, you can get
375 access from other machines without bothering Jeff, thus:</para>
378 <para>Generate a public/private key pair on the new
382 <para>Use ssh to log in to
383 <literal>cvs.haskell.org</literal>, from your old
387 <para>Add the public key for the new machine to the file
388 <literal>$HOME/ssh/authorized_keys</literal> on
389 <literal>cvs.haskell.org</literal>.
390 (<literal>authorized_keys2</literal>, I think, for Version
394 <para>Make sure that the new version of
395 <literal>authorized_keys</literal> still has 600 file
404 <sect2 id="cvs-first">
405 <title>Checking Out a Source Tree</title>
409 <para>Make sure you set your <literal>CVSROOT</literal>
410 environment variable according to either of the remote
411 methods above. The Approved Way to check out a source tree
412 is as follows:</para>
415 $ cvs checkout fpconfig
418 <para>At this point you have a new directory called
419 <literal>fptools</literal> which contains the basic stuff
420 for the fptools suite, including the configuration files and
421 some other junk. </para>
423 <para>[Windows users.] The following messages appear to be harmless:
425 setsockopt IPTOS_LOWDELAY: Invalid argument
426 setsockopt IPTOS_THROUGHPUT: Invalid argument
431 <para>You can call the fptools directory whatever you like,
432 CVS won't mind: </para>
435 $ mv fptools <replaceable>directory</replaceable>
438 <para> NB: after you've read the CVS manual you might be
439 tempted to try</para>
441 $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
444 <para>instead of checking out <literal>fpconfig</literal>
445 and then renaming it. But this doesn't work, and will
446 result in checking out the entire repository instead of just
447 the <literal>fpconfig</literal> bit.</para>
449 $ cd <replaceable>directory</replaceable>
450 $ cvs checkout ghc hslibs libraries
453 <para>The second command here checks out the relevant
454 modules you want to work on. For a GHC build, for instance,
455 you need at least the <literal>ghc</literal>,
456 <literal>hslibs</literal> and <literal>libraries</literal>
457 modules (for a full list of the projects available, see
458 <xref linkend="projects">).</para>
460 <para>Remember that if you do not have
461 <literal>happy</literal> installed, you need to check it out
467 <sect2 id="cvs-committing">
468 <title>Committing Changes</title>
470 <para>This is only if you have read-write access to the
471 repository. For anoncvs users, CVS will issue a "read-only
472 repository" error if you try to commit changes.</para>
476 <para>Build the software, if necessary. Unless you're just
477 working on documentation, you'll probably want to build the
478 software in order to test any changes you make.</para>
482 <para>Make changes. Preferably small ones first.</para>
486 <para>Test them. You can see exactly what changes you've
487 made by using the <literal>cvs diff</literal> command:</para>
491 <para>lists all the changes (using the
492 <literal>diff</literal> command) in and below the current
493 directory. In emacs, <literal>C-c C-v =</literal> runs
494 <literal>cvs diff</literal> on the current buffer and shows
495 you the results.</para>
499 <para>If you changed something in the
500 <literal>fptools/libraries</literal> subdirectories, also run
501 <literal>make html</literal> to check if the documentation can
502 be generated successfully, too.</para>
506 <para>Before checking in a change, you need to update your
513 <para>This pulls in any changes that other people have made,
514 and merges them with yours. If there are any conflicts, CVS
515 will tell you, and you'll have to resolve them before you
516 can check your changes in. The documentation describes what
517 to do in the event of a conflict.</para>
519 <para>It's not always necessary to do a full cvs update
520 before checking in a change, since CVS will always tell you
521 if you try to check in a file that someone else has changed.
522 However, you should still update at regular intervals to
523 avoid making changes that don't work in conjuction with
524 changes that someone else made. Keeping an eye on what goes
525 by on the mailing list can help here.</para>
529 <para>When you're happy that your change isn't going to
530 break anything, check it in. For a one-file change:</para>
533 $ cvs commit <replaceable>filename</replaceable>
536 <para>CVS will then pop up an editor for you to enter a
537 "commit message", this is just a short description
538 of what your change does, and will be kept in the history of
541 <para>If you're using emacs, simply load up the file into a
542 buffer and type <literal>C-x C-q</literal>, and emacs will
543 prompt for a commit message and then check in the file for
546 <para>For a multiple-file change, things are a bit
547 trickier. There are several ways to do this, but this is the
548 way I find easiest. First type the commit message into a
549 temporary file. Then either</para>
552 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
555 <para>or, if nothing else has changed in this part of the
559 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
562 <para>where <replaceable>directory</replaceable> is a common
563 parent directory for all your changes, and
564 <replaceable>commit-message</replaceable> is the name of the
565 file containing the commit message.</para>
567 <para>Shortly afterwards, you'll get some mail from the
568 relevant mailing list saying which files changed, and giving
569 the commit message. For a multiple-file change, you should
570 still get only <emphasis>one</emphasis> message.</para>
575 <sect2 id="cvs-update">
576 <title>Updating Your Source Tree</title>
578 <para>It can be tempting to cvs update just part of a source
579 tree to bring in some changes that someone else has made, or
580 before committing your own changes. This is NOT RECOMMENDED!
581 Quite often changes in one part of the tree are dependent on
582 changes in another part of the tree (the
583 <literal>mk/*.mk</literal> files are a good example where
584 problems crop up quite often). Having an inconsistent tree is a
585 major cause of headaches. </para>
587 <para>So, to avoid a lot of hassle, follow this recipe for
588 updating your tree. Usually you will only want to run cvs update
589 in the sub-projects because running <literal>cvs update -Pd</literal>
590 on top-level will also retrieve any directories you intentionally did
591 not check out:</para>
595 $ cvs update -P 2>&1 | tee log</screen>
597 <para>Look at the log file, and fix any conflicts (denoted by a
598 <quote>C</quote> in the first column). New directories may have
599 appeared in the repository; CVS doesn't check these out by
600 default, so to get new directories you have to explicitly do
602 $ cvs update -d</screen>
603 in each project subdirectory. Don't do this at the top level,
604 because then <emphasis>all</emphasis> the projects will be
607 <para>If you're using multiple build trees, then for every build
608 tree you have pointing at this source tree, you need to update
609 the links in case any new files have appeared: </para>
612 $ cd <replaceable>build-tree</replaceable>
613 $ lndir <replaceable>source-tree</replaceable>
616 <para>Some files might have been removed, so you need to remove
617 the links pointing to these non-existent files:</para>
620 $ find . -xtype l -exec rm '{}' \;
623 <para>To be <emphasis>really</emphasis> safe, you should do
626 <screen>$ gmake all</screen>
628 <para>from the top-level, to update the dependencies and build
629 any changed files. </para>
632 <sect2 id="cvs-tags">
633 <title>GHC Tag Policy</title>
635 <para>If you want to check out a particular version of GHC,
636 you'll need to know how we tag versions in the repository. The
637 policy (as of 4.04) is:</para>
641 <para>The tree is branched before every major release. The
642 branch tag is <literal>ghc-x-xx-branch</literal>, where
643 <literal>x-xx</literal> is the version number of the release
644 with the <literal>'.'</literal> replaced by a
645 <literal>'-'</literal>. For example, the 4.04 release lives
646 on <literal>ghc-4-04-branch</literal>.</para>
650 <para>The release itself is tagged with
651 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
652 called <literal>ghc-4-06</literal>.</para>
656 <para>We didn't always follow these guidelines, so to see
657 what tags there are for previous versions, do <literal>cvs
658 log</literal> on a file that's been around for a while (like
659 <literal>fptools/ghc/README</literal>).</para>
663 <para>So, to check out a fresh GHC 4.06 tree you would
667 $ cvs co -r ghc-4-06 fpconfig
669 $ cvs co -r ghc-4-06 ghc hslibs
673 <sect2 id="cvs-hints">
674 <title>General Hints</title>
678 <para>As a general rule: commit changes in small units,
679 preferably addressing one issue or implementing a single
680 feature. Provide a descriptive log message so that the
681 repository records exactly which changes were required to
682 implement a given feature/fix a bug. I've found this
683 <emphasis>very</emphasis> useful in the past for finding out
684 when a particular bug was introduced: you can just wind back
685 the CVS tree until the bug disappears.</para>
689 <para>Keep the sources at least *buildable* at any given
690 time. No doubt bugs will creep in, but it's quite easy to
691 ensure that any change made at least leaves the tree in a
692 buildable state. We do nightly builds of GHC to keep an eye
693 on what things work/don't work each day and how we're doing
694 in relation to previous verions. This idea is truely wrecked
695 if the compiler won't build in the first place!</para>
699 <para>To check out extra bits into an already-checked-out
700 tree, use the following procedure. Suppose you have a
701 checked-out fptools tree containing just ghc, and you want
702 to add nofib to it:</para>
713 $ cvs update -d nofib
716 <para>(the -d flag tells update to create a new
717 directory). If you just want part of the nofib suite, you
722 $ cvs checkout nofib/spectral
725 <para>This works because <literal>nofib</literal> is a
726 module in its own right, and spectral is a subdirectory of
727 the nofib module. The path argument to checkout must always
728 start with a module name. There's no equivalent form of this
729 command using <literal>update</literal>.</para>
735 <sect1 id="projects">
736 <title>What projects are there?</title>
738 <para>The <literal>fptools</literal> suite consists of several
739 <firstterm>projects</firstterm>, most of which can be downloaded,
740 built and installed individually. Each project corresponds to a
741 subdirectory in the source tree, and if checking out from CVS then
742 each project can be checked out individually by sitting in the top
743 level of your source tree and typing <command>cvs checkout
744 <replaceable>project</replaceable></command>.</para>
746 <para>Here is a list of the projects currently available:</para>
750 <term><literal>ghc</literal></term>
751 <indexterm><primary><literal>ghc</literal></primary>
752 <secondary>project</secondary></indexterm>
754 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
755 Haskell Compiler</ulink> (minus libraries). Absolutely
756 required for building GHC.</para>
761 <term><literal>glafp-utils</literal></term>
762 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
764 <para>Utility programs, some of which are used by the
765 build/installation system. Required for pretty much
771 <term><literal>green-card</literal></term>
772 <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
775 url="http://www.haskell.org/greencard/">Green Card</ulink>
776 system for generating Haskell foreign function
782 <term><literal>haggis</literal></term>
783 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
786 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
787 Haskell GUI framework.</para>
792 <term><literal>haddock</literal></term>
793 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
796 url="http://www.haskell.org/haddock/">Haddock</ulink>
797 documentation tool.</para>
802 <term><literal>happy</literal></term>
803 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
806 url="http://www.haskell.org/happy/">Happy</ulink> Parser
812 <term><literal>hdirect</literal></term>
813 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
816 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
817 Haskell interoperability tool.</para>
822 <term><literal>hood</literal></term>
823 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
825 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
826 Object Observation Debugger</ulink>.</para>
831 <term><literal>hslibs</literal></term>
832 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
834 <para>Supplemental libraries for GHC
835 (<emphasis>required</emphasis> for building GHC).</para>
840 <term><literal>libraries</literal></term>
841 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
843 <para>Hierarchical Haskell library suite
844 (<emphasis>required</emphasis> for building GHC).</para>
849 <term><literal>mhms</literal></term>
850 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
852 <para>The Modular Haskell Metric System.</para>
857 <term><literal>nofib</literal></term>
858 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
860 <para>The NoFib suite: A collection of Haskell programs used
861 primarily for benchmarking.</para>
866 <term><literal>testsuite</literal></term>
867 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
869 <para>A testing framework, including GHC's regression test
875 <para>So, to build GHC you need at least the
876 <literal>ghc</literal>, <literal>libraries</literal> and
877 <literal>hslibs</literal> projects (a GHC source distribution will
878 already include the bits you need).</para>
881 <sect1 id="sec-build-checks">
882 <title>Things to check before you start</title>
884 <para>Here's a list of things to check before you get
890 <indexterm><primary>Disk space needed</primary></indexterm>
891 <para>Disk space needed: from about 100Mb for a basic GHC
892 build, up to probably 500Mb for a GHC build with everything
893 included (libraries built several different ways,
898 <para>Use an appropriate machine / operating system. <xref
899 linkend="sec-port-info"> lists the supported platforms; if
900 yours isn't amongst these then you can try porting GHC (see
901 <xref linkend="sec-porting-ghc">).</para>
905 <para>Be sure that the “pre-supposed” utilities are
906 installed. <Xref LinkEnd="sec-pre-supposed">
911 <para>If you have any problem when building or installing the
912 Glasgow tools, please check the “known pitfalls” (<Xref
913 LinkEnd="sec-build-pitfalls">). Also check the FAQ for the
914 version you're building, which is part of the User's Guide and
915 available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
918 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
920 <para>If you feel there is still some shortcoming in our
921 procedure or instructions, please report it.</para>
923 <para>For GHC, please see the <ulink
924 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
925 section of the GHC Users' Guide</ulink>, to maximise the
926 usefulness of your report.</para>
928 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
929 <para>If in doubt, please send a message to
930 <email>glasgow-haskell-bugs@haskell.org</email>.
931 <indexterm><primary>bugs</primary><secondary>mailing
932 list</secondary></indexterm></para>
937 <sect1 id="sec-port-info">
938 <title>What machines the Glasgow tools run on</title>
940 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
941 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
942 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
944 <para>The main question is whether or not the Haskell compiler
945 (GHC) runs on your platform.</para>
947 <para>A “platform” is a
948 architecture/manufacturer/operating-system combination, such as
949 <literal>sparc-sun-solaris2</literal>. Other common ones are
950 <literal>alpha-dec-osf2</literal>,
951 <literal>hppa1.1-hp-hpux9</literal>,
952 <literal>i386-unknown-linux</literal>,
953 <literal>i386-unknown-solaris2</literal>,
954 <literal>i386-unknown-freebsd</literal>,
955 <literal>i386-unknown-cygwin32</literal>,
956 <literal>m68k-sun-sunos4</literal>,
957 <literal>mips-sgi-irix5</literal>,
958 <literal>sparc-sun-sunos4</literal>,
959 <literal>sparc-sun-solaris2</literal>,
960 <literal>powerpc-ibm-aix</literal>.</para>
962 <para>Some libraries may only work on a limited number of
963 platforms; for example, a sockets library is of no use unless the
964 operating system supports the underlying BSDisms.</para>
967 <title>What platforms the Haskell compiler (GHC) runs on</title>
969 <indexterm><primary>fully-supported platforms</primary></indexterm>
970 <indexterm><primary>native-code generator</primary></indexterm>
971 <indexterm><primary>registerised ports</primary></indexterm>
972 <indexterm><primary>unregisterised ports</primary></indexterm>
974 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
975 native-code generator; (b) next best is a
976 “registerised” port; (c) the bare minimum is an
977 “unregisterised” port.
978 (“Unregisterised” is so terrible that we won't say
979 more about it).</para>
981 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
982 FreeBSD and Linux, so those are the best supported platforms,
983 unsurprisingly.</para>
985 <para>Here's everything that's known about GHC ports. We
986 identify platforms by their “canonical”
987 CPU/Manufacturer/OS triple.</para>
991 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
992 <indexterm><primary>alpha-dec-osf</primary></indexterm>
993 <indexterm><primary>alpha-dec-linux</primary></indexterm>
994 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
995 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
996 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
999 <para>The OSF port is currently working (as of GHC version
1000 5.02.1) and well supported. The native code generator is
1001 currently non-working. Other operating systems will
1002 require some minor porting.</para>
1007 <term>sparc-sun-sunos4</term>
1008 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
1010 <para>Probably works with minor tweaks, hasn't been tested
1016 <term>sparc-sun-solaris2</term>
1017 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
1019 <para>Fully supported (at least for Solaris 2.7),
1020 including native-code generator.</para>
1025 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
1026 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1028 <para>A registerised port is available for version 4.08,
1029 but GHC hasn't been built on that platform since (as far
1030 as we know). No native-code generator.</para>
1035 <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
1036 <indexterm><primary>i386-*-linux</primary></indexterm>
1038 <para>GHC works registerised and has a native code
1039 generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
1040 or later. NOTE about <literal>glibc</literal> versions:
1041 GHC binaries built on a system running <literal>glibc
1042 2.0</literal> won't work on a system running
1043 <literal>glibc 2.1</literal>, and vice versa. In general,
1044 don't expect compatibility between
1045 <literal>glibc</literal> versions, even if the shared
1046 library version hasn't changed.</para>
1051 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
1053 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1055 <para>GHC works registerised. Pre-built packages are
1056 available in the native package format, so if you just
1057 need binaries you're better off just installing the
1058 package (it might even be on your installation
1064 <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
1065 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1067 <para>Supported, with native code generator. Packages are
1068 available through the ports system in the native package
1074 <term>i386-unknown-netbsd (PCs running NetBSD and
1076 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1078 <para>Will require some minor porting effort, but should
1079 work registerised.</para>
1084 <term>i386-unknown-mingw32 (PCs running Windows)</term>
1085 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1087 <para>Fully supported under Win9x, WinNT, Win2k, and
1088 WinXP. Includes a native code generator. Building from
1089 source requires a recent <ulink
1090 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1091 to be installed.</para>
1096 <term>ia64-unknown-linux</term>
1097 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1099 <para>GHC currently works unregisterised. A registerised
1100 port is in progress.</para>
1105 <term>mips-sgi-irix5</term>
1106 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1108 <para>Port has worked in the past, but hasn't been tested
1109 for some time (and will certainly have rotted in various
1110 ways). As usual, we don't have access to machines and
1111 there hasn't been an overwhelming demand for this port,
1112 but feel free to get in touch.</para>
1117 <term>powerpc-ibm-aix</term>
1118 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1120 <para>Port currently doesn't work, needs some minimal
1121 porting effort. As usual, we don't have access to
1122 machines and there hasn't been an overwhelming demand for
1123 this port, but feel free to get in touch.</para>
1128 <term>powerpc-apple-darwin</term>
1129 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1131 <para>Supported registerised. No native code
1137 <term>powerpc-apple-linux</term>
1138 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1140 <para>Not supported (yet).</para>
1145 <para>Various other systems have had GHC ported to them in the
1146 distant past, including various Motorola 68k boxes. The 68k
1147 support still remains, but porting to one of these systems will
1148 certainly be a non-trivial task.</para>
1152 <title>What machines the other tools run on</title>
1154 <para>Unless you hear otherwise, the other tools work if GHC
1160 <sect1 id="sec-pre-supposed">
1161 <title>Installing pre-supposed utilities</title>
1163 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1164 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1166 <para>Here are the gory details about some utility programs you
1167 may need; <command>perl</command>, <command>gcc</command> and
1168 <command>happy</command> are the only important
1169 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1170 important if you're going for Parallel Haskell.) The
1171 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1172 script will tell you if you are missing something.</para>
1178 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1179 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1181 <para>GHC is required to build many of the tools, including
1182 GHC itself. If you need to port GHC to your platform
1183 because there isn't a binary distribution of GHC available,
1184 then see <xref linkend="sec-porting-ghc">.</para>
1186 <para>Which version of GHC you need will depend on the
1187 packages you intend to build. GHC itself will normally
1188 build using one of several older versions of itself - check
1189 the announcement or release notes for details.</para>
1195 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1196 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1198 <para><emphasis>You have to have Perl to proceed!</emphasis>
1199 Perl version 5 at least is required. GHC has been known to
1200 tickle bugs in Perl, so if you find that Perl crashes when
1201 running GHC try updating (or downgrading) your Perl
1202 installation. Versions of Perl that we use and are known to
1203 be fairly stable are 5.005 and 5.6.1.</para>
1205 <para>For Win32 platforms, you should use the binary
1206 supplied in the InstallShield (copy it to
1207 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1210 <para>Perl should be put somewhere so that it can be invoked
1211 by the <literal>#!</literal> script-invoking
1212 mechanism. The full pathname may need to be less than 32
1213 characters long on some systems.</para>
1218 <term>GNU C (<command>gcc</command>)</term>
1219 <indexterm><primary>pre-supposed: GCC (GNU C
1220 compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
1221 compiler), pre-supposed</primary></indexterm>
1223 <para>We recommend using GCC version 2.95.2 on all
1224 platforms. Failing that, version 2.7.2 is stable on most
1225 platforms. Earlier versions of GCC can be assumed not to
1226 work, and versions in between 2.7.2 and 2.95.2 (including
1227 <command>egcs</command>) have varying degrees of stability
1228 depending on the platform.</para>
1230 <para>GCC 3.2 is currently known to have problems building
1231 GHC on Sparc, but is stable on x86.</para>
1233 <para>GCC 3.3 currently cannot be used to build GHC, due to
1234 some problems with the new C preprocessor.</para>
1236 <para>If your GCC dies with “internal error” on
1237 some GHC source file, please let us know, so we can report
1238 it and get things improved. (Exception: on iX86
1239 boxes—you may need to fiddle with GHC's
1240 <option>-monly-N-regs</option> option; see the User's
1246 <term>GNU Make</term>
1247 <indexterm><primary>make</primary><secondary>GNU</secondary>
1250 <para>The fptools build system makes heavy use of features
1251 specific to GNU <command>make</command>, so you must have
1252 this installed in order to build any of the fptools
1259 <indexterm><primary>Happy</primary></indexterm>
1261 <para>Happy is a parser generator tool for Haskell, and is
1262 used to generate GHC's parsers. Happy is written in
1263 Haskell, and is a project in the CVS repository
1264 (<literal>fptools/happy</literal>). It can be built from
1265 source, but bear in mind that you'll need GHC installed in
1266 order to build it. To avoid the chicken/egg problem,
1267 install a binary distribution of either Happy or GHC to get
1268 started. Happy distributions are available from <ulink
1269 url="http://www.haskell.org/happy/">Happy's Web
1270 Page</ulink>.</para>
1275 <term>Autoconf</term>
1276 <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
1277 <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
1279 <para>GNU Autoconf is needed if you intend to build from the
1280 CVS sources, it is <emphasis>not</emphasis> needed if you
1281 just intend to build a standard source distribution.</para>
1283 <para>Version 2.52 or later of autoconf is required.
1284 NB. vesrion 2.13 will no longer work, as of GHC version
1287 <para>Autoconf builds the <command>configure</command>
1288 script from <filename>configure.in</filename> and
1289 <filename>aclocal.m4</filename>. If you modify either of
1290 these files, you'll need <command>autoconf</command> to
1291 rebuild <filename>configure</filename>.</para>
1296 <term><command>sed</command></term>
1297 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1298 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1300 <para>You need a working <command>sed</command> if you are
1301 going to build from sources. The build-configuration stuff
1302 needs it. GNU sed version 2.0.4 is no good! It has a bug
1303 in it that is tickled by the build-configuration. 2.0.5 is
1304 OK. Others are probably OK too (assuming we don't create too
1305 elaborate configure scripts.)</para>
1310 <para>One <literal>fptools</literal> project is worth a quick note
1311 at this point, because it is useful for all the others:
1312 <literal>glafp-utils</literal> contains several utilities which
1313 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1314 Like <command>lndir</command> for creating symbolic link
1317 <sect2 id="pre-supposed-gph-tools">
1318 <title>Tools for building parallel GHC (GPH)</title>
1322 <term>PVM version 3:</term>
1323 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1324 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1326 <para>PVM is the Parallel Virtual Machine on which
1327 Parallel Haskell programs run. (You only need this if you
1328 plan to run Parallel Haskell. Concurrent Haskell, which
1329 runs concurrent threads on a uniprocessor doesn't need
1330 it.) Underneath PVM, you can have (for example) a network
1331 of workstations (slow) or a multiprocessor box
1334 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1335 It is readily available on the net; I think I got it from
1336 <literal>research.att.com</literal>, in
1337 <filename>netlib</filename>.</para>
1339 <para>A PVM installation is slightly quirky, but easy to
1340 do. Just follow the <filename>Readme</filename>
1341 instructions.</para>
1346 <term><command>bash</command>:</term>
1347 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1349 <para>Sadly, the <command>gr2ps</command> script, used to
1350 convert “parallelism profiles” to PostScript,
1351 is written in Bash (GNU's Bourne Again shell). This bug
1352 will be fixed (someday).</para>
1358 <sect2 id="pre-supposed-other-tools">
1359 <title>Other useful tools</title>
1364 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1365 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1367 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1368 to build a couple of utilities in
1369 <literal>glafp-utils</literal>. Depending on your
1370 operating system, the supplied <command>lex</command> may
1371 or may not work; you should get the GNU version.</para>
1376 <para>More tools are required if you want to format the documentation
1377 that comes with GHC and other fptools projects. See <xref
1378 linkend="building-docs">.</para>
1382 <sect1 id="sec-building-from-source">
1383 <title>Building from source</title>
1385 <indexterm><primary>Building from source</primary></indexterm>
1386 <indexterm><primary>Source, building from</primary></indexterm>
1388 <para>You've been rash enough to want to build some of the Glasgow
1389 Functional Programming tools (GHC, Happy, nofib, etc.) from
1390 source. You've slurped the source, from the CVS repository or
1391 from a source distribution, and now you're sitting looking at a
1392 huge mound of bits, wondering what to do next.</para>
1394 <para>Gingerly, you type <command>make</command>. Wrong
1397 <para>This rest of this guide is intended for duffers like me, who
1398 aren't really interested in Makefiles and systems configurations,
1399 but who need a mental model of the interlocking pieces so that
1400 they can make them work, extend them consistently when adding new
1401 software, and lay hands on them gently when they don't
1404 <sect2 id="quick-start">
1405 <title>Quick Start</title>
1407 <para>If you are starting from a source distribution, and just
1408 want a completely standard build, then the following should
1411 <screen>$ ./configure
1416 <para>For GHC, this will do a 2-stage bootstrap build of the
1417 compiler, with profiling libraries, and install the
1420 <para>If you want to do anything at all non-standard, or you
1421 want to do some development, read on...</para>
1424 <sect2 id="sec-source-tree">
1425 <title>Your source tree</title>
1427 <para>The source code is held in your <emphasis>source
1428 tree</emphasis>. The root directory of your source tree
1429 <emphasis>must</emphasis> contain the following directories and
1434 <para><filename>Makefile</filename>: the root
1439 <para><filename>mk/</filename>: the directory that contains
1440 the main Makefile code, shared by all the
1441 <literal>fptools</literal> software.</para>
1445 <para><filename>configure.in</filename>,
1446 <filename>config.sub</filename>,
1447 <filename>config.guess</filename>: these files support the
1448 configuration process.</para>
1452 <para><filename>install-sh</filename>.</para>
1456 <para>All the other directories are individual
1457 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1458 system—for example, the Glasgow Haskell Compiler
1459 (<literal>ghc</literal>), the Happy parser generator
1460 (<literal>happy</literal>), the <literal>nofib</literal>
1461 benchmark suite, and so on. You can have zero or more of these.
1462 Needless to say, some of them are needed to build others.</para>
1464 <para>The important thing to remember is that even if you want
1465 only one project (<literal>happy</literal>, say), you must have
1466 a source tree whose root directory contains
1467 <filename>Makefile</filename>, <filename>mk/</filename>,
1468 <filename>configure.in</filename>, and the project(s) you want
1469 (<filename>happy/</filename> in this case). You cannot get by
1470 with just the <filename>happy/</filename> directory.</para>
1474 <title>Build trees</title>
1475 <indexterm><primary>build trees</primary></indexterm>
1476 <indexterm><primary>link trees, for building</primary></indexterm>
1478 <para>If you just want to build the software once on a single
1479 platform, then your source tree can also be your build tree, and
1480 you can skip the rest of this section.</para>
1482 <para>We often want to build multiple versions of our software
1483 for different architectures, or with different options
1484 (e.g. profiling). It's very desirable to share a single copy of
1485 the source code among all these builds.</para>
1487 <para>So for every source tree we have zero or more
1488 <emphasis>build trees</emphasis>. Each build tree is initially
1489 an exact copy of the source tree, except that each file is a
1490 symbolic link to the source file, rather than being a copy of
1491 the source file. There are “standard” Unix
1492 utilities that make such copies, so standard that they go by
1494 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1495 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1496 are two (If you don't have either, the source distribution
1497 includes sources for the X11
1498 <command>lndir</command>—check out
1499 <filename>fptools/glafp-utils/lndir</filename>). See <Xref
1500 LinkEnd="sec-storysofar"> for a typical invocation.</para>
1502 <para>The build tree does not need to be anywhere near the
1503 source tree in the file system. Indeed, one advantage of
1504 separating the build tree from the source is that the build tree
1505 can be placed in a non-backed-up partition, saving your systems
1506 support people from backing up untold megabytes of
1507 easily-regenerated, and rapidly-changing, gubbins. The golden
1508 rule is that (with a single exception—<XRef
1509 LinkEnd="sec-build-config">) <emphasis>absolutely everything in
1510 the build tree is either a symbolic link to the source tree, or
1511 else is mechanically generated</emphasis>. It should be
1512 perfectly OK for your build tree to vanish overnight; an hour or
1513 two compiling and you're on the road again.</para>
1515 <para>You need to be a bit careful, though, that any new files
1516 you create (if you do any development work) are in the source
1517 tree, not a build tree!</para>
1519 <para>Remember, that the source files in the build tree are
1520 <emphasis>symbolic links</emphasis> to the files in the source
1521 tree. (The build tree soon accumulates lots of built files like
1522 <filename>Foo.o</filename>, as well.) You can
1523 <emphasis>delete</emphasis> a source file from the build tree
1524 without affecting the source tree (though it's an odd thing to
1525 do). On the other hand, if you <emphasis>edit</emphasis> a
1526 source file from the build tree, you'll edit the source-tree
1527 file directly. (You can set up Emacs so that if you edit a
1528 source file from the build tree, Emacs will silently create an
1529 edited copy of the source file in the build tree, leaving the
1530 source file unchanged; but the danger is that you think you've
1531 edited the source file whereas actually all you've done is edit
1532 the build-tree copy. More commonly you do want to edit the
1533 source file.)</para>
1535 <para>Like the source tree, the top level of your build tree
1536 must be (a linked copy of) the root directory of the
1537 <literal>fptools</literal> suite. Inside Makefiles, the root of
1538 your build tree is called
1539 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1540 In the rest of this document path names are relative to
1541 <constant>$(FPTOOLS_TOP)</constant> unless
1542 otherwise stated. For example, the file
1543 <filename>ghc/mk/target.mk</filename> is actually
1544 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
1547 <sect2 id="sec-build-config">
1548 <title>Getting the build you want</title>
1550 <para>When you build <literal>fptools</literal> you will be
1551 compiling code on a particular <emphasis>host
1552 platform</emphasis>, to run on a particular <emphasis>target
1553 platform</emphasis> (usually the same as the host
1554 platform)<indexterm><primary>platform</primary></indexterm>.
1555 The difficulty is that there are minor differences between
1556 different platforms; minor, but enough that the code needs to be
1557 a bit different for each. There are some big differences too:
1558 for a different architecture we need to build GHC with a
1559 different native-code generator.</para>
1561 <para>There are also knobs you can turn to control how the
1562 <literal>fptools</literal> software is built. For example, you
1563 might want to build GHC optimised (so that it runs fast) or
1564 unoptimised (so that you can compile it fast after you've
1565 modified it. Or, you might want to compile it with debugging on
1566 (so that extra consistency-checking code gets included) or off.
1569 <para>All of this stuff is called the
1570 <emphasis>configuration</emphasis> of your build. You set the
1571 configuration using a three-step process.</para>
1575 <term>Step 1: get ready for configuration.</term>
1577 <para>NOTE: if you're starting from a source distribution,
1578 rather than CVS sources, you can skip this step.</para>
1580 <para>Change directory to
1581 <constant>$(FPTOOLS_TOP)</constant> and
1583 <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
1584 (with no arguments). This GNU program converts
1585 <filename><constant>$(FPTOOLS_TOP)</constant>/configure.in</filename>
1586 to a shell script called
1587 <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
1590 <para>Some projects, including GHC, have their own
1591 configure script. If there's an
1592 <constant>$(FPTOOLS_TOP)/<project>/configure.in</constant>,
1593 then you need to run <command>autoconf</command> in that
1594 directory too.</para>
1596 <para>Both these steps are completely
1597 platform-independent; they just mean that the
1598 human-written file (<filename>configure.in</filename>) can
1599 be short, although the resulting shell script,
1600 <command>configure</command>, and
1601 <filename>mk/config.h.in</filename>, are long.</para>
1606 <term>Step 2: system configuration.</term>
1608 <para>Runs the newly-created <command>configure</command>
1609 script, thus:</para>
1612 ./configure <optional><parameter>args</parameter></optional>
1615 <para><command>configure</command>'s mission is to scurry
1616 round your computer working out what architecture it has,
1617 what operating system, whether it has the
1618 <Function>vfork</Function> system call, where
1619 <command>yacc</command> is kept, whether
1620 <command>gcc</command> is available, where various obscure
1621 <literal>#include</literal> files are, whether it's a
1622 leap year, and what the systems manager had for lunch. It
1623 communicates these snippets of information in two
1630 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1632 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1633 substituting for things between
1634 “<literal>@</literal>” brackets. So,
1635 “<literal>@HaveGcc@</literal>” will be
1636 replaced by “<literal>YES</literal>” or
1637 “<literal>NO</literal>” depending on what
1638 <command>configure</command> finds.
1639 <filename>mk/config.mk</filename> is included by every
1640 Makefile (directly or indirectly), so the
1641 configuration information is thereby communicated to
1642 all Makefiles.</para>
1646 <para> It translates
1647 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1649 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1650 The latter is <literal>#include</literal>d by
1651 various C programs, which can thereby make use of
1652 configuration information.</para>
1656 <para><command>configure</command> takes some optional
1657 arguments. Use <literal>./configure --help</literal> to
1658 get a list of the available arguments. Here are some of
1659 the ones you might need:</para>
1663 <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
1664 <indexterm><primary><literal>--with-ghc</literal></primary>
1667 <para>Specifies the path to an installed GHC which
1668 you would like to use. This compiler will be used
1669 for compiling GHC-specific code (eg. GHC itself).
1670 This option <emphasis>cannot</emphasis> be specified
1671 using <filename>build.mk</filename> (see later),
1672 because <command>configure</command> needs to
1673 auto-detect the version of GHC you're using. The
1674 default is to look for a compiler named
1675 <literal>ghc</literal> in your path.</para>
1680 <term><literal>--with-hc=<parameter>path</parameter></literal></term>
1681 <indexterm><primary><literal>--with-hc</literal></primary>
1684 <para>Specifies the path to any installed Haskell
1685 compiler. This compiler will be used for compiling
1686 generic Haskell code. The default is to use
1687 <literal>ghc</literal>.</para>
1692 <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
1693 <indexterm><primary><literal>--with-gcc</literal></primary>
1696 <para>Specifies the path to the installed GCC. This
1697 compiler will be used to compile all C files,
1698 <emphasis>except</emphasis> any generated by the
1699 installed Haskell compiler, which will have its own
1700 idea of which C compiler (if any) to use. The
1701 default is to use <literal>gcc</literal>.</para>
1706 <para><command>configure</command> caches the results of
1707 its run in <filename>config.cache</filename>. Quite often
1708 you don't want that; you're running
1709 <command>configure</command> a second time because
1710 something has changed. In that case, simply delete
1711 <filename>config.cache</filename>.</para>
1716 <term>Step 3: build configuration.</term>
1718 <para>Next, you say how this build of
1719 <literal>fptools</literal> is to differ from the standard
1720 defaults by creating a new file
1721 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1722 <emphasis>in the build tree</emphasis>. This file is the
1723 one and only file you edit in the build tree, precisely
1724 because it says how this build differs from the source.
1725 (Just in case your build tree does die, you might want to
1726 keep a private directory of <filename>build.mk</filename>
1727 files, and use a symbolic link in each build tree to point
1728 to the appropriate one.) So
1729 <filename>mk/build.mk</filename> never exists in the
1730 source tree—you create one in each build tree from
1731 the template. We'll discuss what to put in it
1737 <para>And that's it for configuration. Simple, eh?</para>
1739 <para>What do you put in your build-specific configuration file
1740 <filename>mk/build.mk</filename>? <emphasis>For almost all
1741 purposes all you will do is put make variable definitions that
1742 override those in</emphasis>
1743 <filename>mk/config.mk.in</filename>. The whole point of
1744 <filename>mk/config.mk.in</filename>—and its derived
1745 counterpart <filename>mk/config.mk</filename>—is to define
1746 the build configuration. It is heavily commented, as you will
1747 see if you look at it. So generally, what you do is look at
1748 <filename>mk/config.mk.in</filename>, and add definitions in
1749 <filename>mk/build.mk</filename> that override any of the
1750 <filename>config.mk</filename> definitions that you want to
1751 change. (The override occurs because the main boilerplate file,
1752 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1753 includes <filename>build.mk</filename> after
1754 <filename>config.mk</filename>.)</para>
1756 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1757 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1759 <para>For example, <filename>config.mk.in</filename> contains
1760 the definition:</para>
1763 GhcHcOpts=-O -Rghc-timing
1766 <para>The accompanying comment explains that this is the list of
1767 flags passed to GHC when building GHC itself. For doing
1768 development, it is wise to add <literal>-DDEBUG</literal>, to
1769 enable debugging code. So you would add the following to
1770 <filename>build.mk</filename>:</para>
1772 <para>or, if you prefer,</para>
1775 GhcHcOpts += -DDEBUG
1778 <para>GNU <command>make</command> allows existing definitions to
1779 have new text appended using the “<literal>+=</literal>”
1780 operator, which is quite a convenient feature.)</para>
1782 <para>If you want to remove the <literal>-O</literal> as well (a
1783 good idea when developing, because the turn-around cycle gets a
1784 lot quicker), you can just override
1785 <literal>GhcLibHcOpts</literal> altogether:</para>
1788 GhcHcOpts=-DDEBUG -Rghc-timing
1791 <para>When reading <filename>config.mk.in</filename>, remember
1792 that anything between “@...@” signs is going to be substituted
1793 by <command>configure</command> later. You
1794 <emphasis>can</emphasis> override the resulting definition if
1795 you want, but you need to be a bit surer what you are doing.
1796 For example, there's a line that says:</para>
1802 <para>This defines the Make variables <constant>YACC</constant>
1803 to the pathname for a <command>yacc</command> that
1804 <command>configure</command> finds somewhere. If you have your
1805 own pet <command>yacc</command> you want to use instead, that's
1806 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1812 <para>You do not <emphasis>have</emphasis> to have a
1813 <filename>mk/build.mk</filename> file at all; if you don't,
1814 you'll get all the default settings from
1815 <filename>mk/config.mk.in</filename>.</para>
1817 <para>You can also use <filename>build.mk</filename> to override
1818 anything that <command>configure</command> got wrong. One place
1819 where this happens often is with the definition of
1820 <constant>FPTOOLS_TOP_ABS</constant>: this
1821 variable is supposed to be the canonical path to the top of your
1822 source tree, but if your system uses an automounter then the
1823 correct directory is hard to find automatically. If you find
1824 that <command>configure</command> has got it wrong, just put the
1825 correct definition in <filename>build.mk</filename>.</para>
1829 <sect2 id="sec-storysofar">
1830 <title>The story so far</title>
1832 <para>Let's summarise the steps you need to carry to get
1833 yourself a fully-configured build tree from scratch.</para>
1837 <para> Get your source tree from somewhere (CVS repository
1838 or source distribution). Say you call the root directory
1839 <filename>myfptools</filename> (it does not have to be
1840 called <filename>fptools</filename>). Make sure that you
1841 have the essential files (see <XRef
1842 LinkEnd="sec-source-tree">).</para>
1847 <para>(Optional) Use <command>lndir</command> or
1848 <command>mkshadowdir</command> to create a build tree.</para>
1852 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1855 <para>(N.B. <command>mkshadowdir</command>'s first argument
1856 is taken relative to its second.) You probably want to give
1857 the build tree a name that suggests its main defining
1858 characteristic (in your mind at least), in case you later
1863 <para>Change directory to the build tree. Everything is
1864 going to happen there now.</para>
1867 $ cd /scratch/joe-bloggs/myfptools-sun4
1873 <para>Prepare for system configuration:</para>
1879 <para>(You can skip this step if you are starting from a
1880 source distribution, and you already have
1881 <filename>configure</filename> and
1882 <filename>mk/config.h.in</filename>.)</para>
1884 <para>Some projects, including GHC itself, have their own
1885 configure scripts, so it is necessary to run autoconf again
1886 in the appropriate subdirectories. eg:</para>
1889 $ (cd ghc; autoconf)
1894 <para>Do system configuration:</para>
1900 <para>Don't forget to check whether you need to add any
1901 arguments to <literal>configure</literal>; for example, a
1902 common requirement is to specify which GHC to use with
1903 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1907 <para>Create the file <filename>mk/build.mk</filename>,
1908 adding definitions for your desired configuration
1917 <para>You can make subsequent changes to
1918 <filename>mk/build.mk</filename> as often as you like. You do
1919 not have to run any further configuration programs to make these
1920 changes take effect. In theory you should, however, say
1921 <command>gmake clean</command>, <command>gmake all</command>,
1922 because configuration option changes could affect
1923 anything—but in practice you are likely to know what's
1928 <title>Making things</title>
1930 <para>At this point you have made yourself a fully-configured
1931 build tree, so you are ready to start building real
1934 <para>The first thing you need to know is that <emphasis>you
1935 must use GNU <command>make</command>, usually called
1936 <command>gmake</command>, not standard Unix
1937 <command>make</command></emphasis>. If you use standard Unix
1938 <command>make</command> you will get all sorts of error messages
1939 (but no damage) because the <literal>fptools</literal>
1940 <command>Makefiles</command> use GNU <command>make</command>'s
1941 facilities extensively.</para>
1943 <para>To just build the whole thing, <command>cd</command> to
1944 the top of your <literal>fptools</literal> tree and type
1945 <command>gmake</command>. This will prepare the tree and build
1946 the various projects in the correct order.</para>
1949 <sect2 id="sec-bootstrapping">
1950 <title>Bootstrapping GHC</title>
1952 <para>GHC requires a 2-stage bootstrap in order to provide
1953 full functionality, including GHCi. By a 2-stage bootstrap, we
1954 mean that the compiler is built once using the installed GHC,
1955 and then again using the compiler built in the first stage. You
1956 can also build a stage 3 compiler, but this normally isn't
1957 necessary except to verify that the stage 2 compiler is working
1960 <para>Note that when doing a bootstrap, the stage 1 compiler
1961 must be built, followed by the runtime system and libraries, and
1962 then the stage 2 compiler. The correct ordering is implemented
1963 by the top-level fptools <filename>Makefile</filename>, so if
1964 you want everything to work automatically it's best to start
1965 <command>make</command> from the top of the tree. When building
1966 GHC, the top-level fptools <filename>Makefile</filename> is set
1967 up to do a 2-stage bootstrap by default (when you say
1968 <command>make</command>). Some other targets it supports
1975 <para>Build everything as normal, including the stage 1
1983 <para>Build the stage 2 compiler only.</para>
1990 <para>Build the stage 3 compiler only.</para>
1995 <term>bootstrap</term> <term>bootstrap2</term>
1997 <para>Build stage 1 followed by stage 2.</para>
2002 <term>bootstrap3</term>
2004 <para>Build stages 1, 2 and 3.</para>
2009 <term>install</term>
2011 <para>Install everything, including the compiler built in
2012 stage 2. To override the stage, say <literal>make install
2013 stage=<replaceable>n</replaceable></literal> where
2014 <replaceable>n</replaceable> is the stage to install.</para>
2019 <para>The top-level <filename>Makefile</filename> also arranges
2020 to do the appropriate <literal>make boot</literal> steps (see
2021 below) before actually building anything.</para>
2023 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2024 and <literal>stage3</literal> targets also work in the
2025 <literal>ghc/compiler</literal> directory, but don't forget that
2026 each stage requires its own <literal>make boot</literal> step:
2027 for example, you must do</para>
2029 <screen>$ make boot stage=2</screen>
2031 <para>before <literal>make stage2</literal> in
2032 <literal>ghc/compiler</literal>.</para>
2035 <sect2 id="sec-standard-targets">
2036 <title>Standard Targets</title>
2037 <indexterm><primary>targets, standard makefile</primary></indexterm>
2038 <indexterm><primary>makefile targets</primary></indexterm>
2040 <para>In any directory you should be able to make the following:</para>
2044 <term><literal>boot</literal></term>
2046 <para>does the one-off preparation required to get ready
2047 for the real work. Notably, it does <command>gmake
2048 depend</command> in all directories that contain programs.
2049 It also builds the necessary tools for compilation to
2052 <para>Invoking the <literal>boot</literal> target
2053 explicitly is not normally necessary. From the top-level
2054 <literal>fptools</literal> directory, invoking
2055 <literal>gmake</literal> causes <literal>gmake boot
2056 all</literal> to be invoked in each of the project
2057 subdirectories, in the order specified by
2058 <literal>$(AllTargets)</literal> in
2059 <literal>config.mk</literal>.</para>
2061 <para>If you're working in a subdirectory somewhere and
2062 need to update the dependencies, <literal>gmake
2063 boot</literal> is a good way to do it.</para>
2068 <term><literal>all</literal></term>
2070 <para>makes all the final target(s) for this Makefile.
2071 Depending on which directory you are in a “final
2072 target” may be an executable program, a library
2073 archive, a shell script, or a Postscript file. Typing
2074 <command>gmake</command> alone is generally the same as
2075 typing <command>gmake all</command>.</para>
2080 <term><literal>install</literal></term>
2082 <para>installs the things built by <literal>all</literal>
2083 (except for the documentation). Where does it install
2084 them? That is specified by
2085 <filename>mk/config.mk.in</filename>; you can override it
2086 in <filename>mk/build.mk</filename>, or by running
2087 <command>configure</command> with command-line arguments
2088 like <literal>--bindir=/home/simonpj/bin</literal>; see
2089 <literal>./configure --help</literal> for the full
2095 <term><literal>install-docs</literal></term>
2097 <para>installs the documentation. Otherwise behaves just
2098 like <literal>install</literal>.</para>
2103 <term><literal>uninstall</literal></term>
2105 <para>reverses the effect of
2106 <literal>install</literal>.</para>
2111 <term><literal>clean</literal></term>
2113 <para>Delete all files from the current directory that are
2114 normally created by building the program. Don't delete
2115 the files that record the configuration, or files
2116 generated by <command>gmake boot</command>. Also preserve
2117 files that could be made by building, but normally aren't
2118 because the distribution comes with them.</para>
2123 <term><literal>distclean</literal></term>
2125 <para>Delete all files from the current directory that are
2126 created by configuring or building the program. If you
2127 have unpacked the source and built the program without
2128 creating any other files, <literal>make
2129 distclean</literal> should leave only the files that were
2130 in the distribution.</para>
2135 <term><literal>mostlyclean</literal></term>
2137 <para>Like <literal>clean</literal>, but may refrain from
2138 deleting a few files that people normally don't want to
2144 <term><literal>maintainer-clean</literal></term>
2146 <para>Delete everything from the current directory that
2147 can be reconstructed with this Makefile. This typically
2148 includes everything deleted by
2149 <literal>distclean</literal>, plus more: C source files
2150 produced by Bison, tags tables, Info files, and so
2153 <para>One exception, however: <literal>make
2154 maintainer-clean</literal> should not delete
2155 <filename>configure</filename> even if
2156 <filename>configure</filename> can be remade using a rule
2157 in the <filename>Makefile</filename>. More generally,
2158 <literal>make maintainer-clean</literal> should not delete
2159 anything that needs to exist in order to run
2160 <filename>configure</filename> and then begin to build the
2166 <term><literal>check</literal></term>
2168 <para>run the test suite.</para>
2173 <para>All of these standard targets automatically recurse into
2174 sub-directories. Certain other standard targets do not:</para>
2178 <term><literal>configure</literal></term>
2180 <para>is only available in the root directory
2181 <constant>$(FPTOOLS_TOP)</constant>; it has
2182 been discussed in <XRef
2183 LinkEnd="sec-build-config">.</para>
2188 <term><literal>depend</literal></term>
2190 <para>make a <filename>.depend</filename> file in each
2191 directory that needs it. This <filename>.depend</filename>
2192 file contains mechanically-generated dependency
2193 information; for example, suppose a directory contains a
2194 Haskell source module <filename>Foo.lhs</filename> which
2195 imports another module <literal>Baz</literal>. Then the
2196 generated <filename>.depend</filename> file will contain
2197 the dependency:</para>
2203 <para>which says that the object file
2204 <filename>Foo.o</filename> depends on the interface file
2205 <filename>Baz.hi</filename> generated by compiling module
2206 <literal>Baz</literal>. The <filename>.depend</filename>
2207 file is automatically included by every Makefile.</para>
2212 <term><literal>binary-dist</literal></term>
2214 <para>make a binary distribution. This is the target we
2215 use to build the binary distributions of GHC and
2221 <term><literal>dist</literal></term>
2223 <para>make a source distribution. Note that this target
2224 does “make distclean” as part of its work;
2225 don't use it if you want to keep what you've built.</para>
2230 <para>Most <filename>Makefile</filename>s have targets other
2231 than these. You can discover them by looking in the
2232 <filename>Makefile</filename> itself.</para>
2236 <title>Using a project from the build tree</title>
2238 <para>If you want to build GHC (say) and just use it direct from
2239 the build tree without doing <literal>make install</literal>
2240 first, you can run the in-place driver script:
2241 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2243 <para> Do <emphasis>NOT</emphasis> use
2244 <filename>ghc/compiler/ghc</filename>, or
2245 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2246 scripts intended for installation, and contain hard-wired paths
2247 to the installed libraries, rather than the libraries in the
2250 <para>Happy can similarly be run from the build tree, using
2251 <filename>happy/src/happy-inplace</filename>.</para>
2255 <title>Fast Making</title>
2257 <indexterm><primary>fastmake</primary></indexterm>
2258 <indexterm><primary>dependencies, omitting</primary></indexterm>
2259 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2261 <para>Sometimes the dependencies get in the way: if you've made
2262 a small change to one file, and you're absolutely sure that it
2263 won't affect anything else, but you know that
2264 <command>make</command> is going to rebuild everything anyway,
2265 the following hack may be useful:</para>
2271 <para>This tells the make system to ignore dependencies and just
2272 build what you tell it to. In other words, it's equivalent to
2273 temporarily removing the <filename>.depend</filename> file in
2274 the current directory (where <command>mkdependHS</command> and
2275 friends store their dependency information).</para>
2277 <para>A bit of history: GHC used to come with a
2278 <command>fastmake</command> script that did the above job, but
2279 GNU make provides the features we need to do it without
2280 resorting to a script. Also, we've found that fastmaking is
2281 less useful since the advent of GHC's recompilation checker (see
2282 the User's Guide section on "Separate Compilation").</para>
2286 <sect1 id="sec-makefile-arch">
2287 <title>The <filename>Makefile</filename> architecture</title>
2288 <indexterm><primary>makefile architecture</primary></indexterm>
2290 <para><command>make</command> is great if everything
2291 works—you type <command>gmake install</command> and lo! the
2292 right things get compiled and installed in the right places. Our
2293 goal is to make this happen often, but somehow it often doesn't;
2294 instead some weird error message eventually emerges from the
2295 bowels of a directory you didn't know existed.</para>
2297 <para>The purpose of this section is to give you a road-map to
2298 help you figure out what is going right and what is going
2302 <title>Debugging</title>
2304 <para>Debugging <filename>Makefile</filename>s is something of a
2305 black art, but here's a couple of tricks that we find
2306 particularly useful. The following command allows you to see
2307 the contents of any make variable in the context of the current
2308 <filename>Makefile</filename>:</para>
2310 <screen>$ make show VALUE=HS_SRCS</screen>
2312 <para>where you can replace <literal>HS_SRCS</literal> with the
2313 name of any variable you wish to see the value of.</para>
2315 <para>GNU make has a <option>-d</option> option which generates
2316 a dump of the decision procedure used to arrive at a conclusion
2317 about which files should be recompiled. Sometimes useful for
2318 tracking down problems with superfluous or missing
2319 recompilations.</para>
2323 <title>A small project</title>
2325 <para>To get started, let us look at the
2326 <filename>Makefile</filename> for an imaginary small
2327 <literal>fptools</literal> project, <literal>small</literal>.
2328 Each project in <literal>fptools</literal> has its own directory
2329 in <constant>FPTOOLS_TOP</constant>, so the
2330 <literal>small</literal> project will have its own directory
2331 <constant>FPOOLS_TOP/small/</constant>. Inside the
2332 <filename>small/</filename> directory there will be a
2333 <filename>Makefile</filename>, looking something like
2336 <indexterm><primary>Makefile, minimal</primary></indexterm>
2339 # Makefile for fptools project "small"
2342 include $(TOP)/mk/boilerplate.mk
2344 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2347 include $(TOP)/target.mk
2350 <para>this <filename>Makefile</filename> has three
2355 <para>The first section includes
2358 One of the most important
2359 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2360 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2365 a file of “boilerplate” code from the level
2366 above (which in this case will be
2367 <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2368 As its name suggests, <filename>boilerplate.mk</filename>
2369 consists of a large quantity of standard
2370 <filename>Makefile</filename> code. We discuss this
2371 boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
2372 <indexterm><primary>include, directive in
2373 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2374 inclusion</primary></indexterm></para>
2376 <para>Before the <literal>include</literal> statement, you
2377 must define the <command>make</command> variable
2378 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2379 to be the directory containing the <filename>mk</filename>
2380 directory in which the <filename>boilerplate.mk</filename>
2381 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2384 include ../mk/boilerplate.mk # NO NO NO
2388 <para>Why? Because the <filename>boilerplate.mk</filename>
2389 file needs to know where it is, so that it can, in turn,
2390 <literal>include</literal> other files. (Unfortunately,
2391 when an <literal>include</literal>d file does an
2392 <literal>include</literal>, the filename is treated relative
2393 to the directory in which <command>gmake</command> is being
2394 run, not the directory in which the
2395 <literal>include</literal>d sits.) In general,
2396 <emphasis>every file <filename>foo.mk</filename> assumes
2398 <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
2399 refers to itself.</emphasis> It is up to the
2400 <filename>Makefile</filename> doing the
2401 <literal>include</literal> to ensure this is the case.</para>
2403 <para>Files intended for inclusion in other
2404 <filename>Makefile</filename>s are written to have the
2405 following property: <emphasis>after
2406 <filename>foo.mk</filename> is <literal>include</literal>d,
2407 it leaves <constant>TOP</constant> containing the same value
2408 as it had just before the <literal>include</literal>
2409 statement</emphasis>. In our example, this invariant
2410 guarantees that the <literal>include</literal> for
2411 <filename>target.mk</filename> will look in the same
2412 directory as that for <filename>boilerplate.mk</filename>.</para>
2416 <para> The second section defines the following standard
2417 <command>make</command> variables:
2418 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2419 (the source files from which is to be built), and
2420 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2421 (the executable binary to be built). We will discuss in
2422 more detail what the “standard variables” are,
2423 and how they affect what happens, in <XRef
2424 LinkEnd="sec-targets">.</para>
2426 <para>The definition for <constant>SRCS</constant> uses the
2427 useful GNU <command>make</command> construct
2428 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2429 which expands to a list of all the files matching the
2430 pattern <literal>pat</literal> in the current directory. In
2431 this example, <constant>SRCS</constant> is set to the list
2432 of all the <filename>.lhs</filename> and
2433 <filename>.c</filename> files in the directory. (Let's
2434 suppose there is one of each, <filename>Foo.lhs</filename>
2435 and <filename>Baz.c</filename>.)</para>
2439 <para>The last section includes a second file of standard
2441 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2442 It contains the rules that tell <command>gmake</command> how
2443 to make the standard targets (<Xref
2444 LinkEnd="sec-standard-targets">). Why, you ask, can't this
2445 standard code be part of
2446 <filename>boilerplate.mk</filename>? Good question. We
2447 discuss the reason later, in <Xref
2448 LinkEnd="sec-boiler-arch">.</para>
2450 <para>You do not <emphasis>have</emphasis> to
2451 <literal>include</literal> the
2452 <filename>target.mk</filename> file. Instead, you can write
2453 rules of your own for all the standard targets. Usually,
2454 though, you will find quite a big payoff from using the
2455 canned rules in <filename>target.mk</filename>; the price
2456 tag is that you have to understand what canned rules get
2457 enabled, and what they do (<Xref
2458 LinkEnd="sec-targets">).</para>
2462 <para>In our example <filename>Makefile</filename>, most of the
2463 work is done by the two <literal>include</literal>d files. When
2464 you say <command>gmake all</command>, the following things
2469 <para><command>gmake</command> figures out that the object
2470 files are <filename>Foo.o</filename> and
2471 <filename>Baz.o</filename>.</para>
2475 <para>It uses a boilerplate pattern rule to compile
2476 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2477 using a Haskell compiler. (Which one? That is set in the
2478 build configuration.)</para>
2482 <para>It uses another standard pattern rule to compile
2483 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2484 using a C compiler. (Ditto.)</para>
2488 <para>It links the resulting <filename>.o</filename> files
2489 together to make <literal>small</literal>, using the Haskell
2490 compiler to do the link step. (Why not use
2491 <command>ld</command>? Because the Haskell compiler knows
2492 what standard libraries to link in. How did
2493 <command>gmake</command> know to use the Haskell compiler to
2494 do the link, rather than the C compiler? Because we set the
2495 variable <constant>HS_PROG</constant> rather than
2496 <constant>C_PROG</constant>.)</para>
2500 <para>All <filename>Makefile</filename>s should follow the above
2501 three-section format.</para>
2505 <title>A larger project</title>
2507 <para>Larger projects are usually structured into a number of
2508 sub-directories, each of which has its own
2509 <filename>Makefile</filename>. (In very large projects, this
2510 sub-structure might be iterated recursively, though that is
2511 rare.) To give you the idea, here's part of the directory
2512 structure for the (rather large) GHC project:</para>
2522 ...source files for documentation...
2525 ...source files for driver...
2528 parser/...source files for parser...
2529 renamer/...source files for renamer...
2533 <para>The sub-directories <filename>docs</filename>,
2534 <filename>driver</filename>, <filename>compiler</filename>, and
2535 so on, each contains a sub-component of GHC, and each has its
2536 own <filename>Makefile</filename>. There must also be a
2537 <filename>Makefile</filename> in
2538 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
2539 It does most of its work by recursively invoking
2540 <command>gmake</command> on the <filename>Makefile</filename>s
2541 in the sub-directories. We say that
2542 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2543 <filename>Makefile</filename></emphasis>, because it does little
2544 except organise its children, while the
2545 <filename>Makefile</filename>s in the sub-directories are all
2546 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2547 principle the sub-directories might themselves contain a
2548 non-leaf <filename>Makefile</filename> and several
2549 sub-sub-directories, but that does not happen in GHC.)</para>
2551 <para>The <filename>Makefile</filename> in
2552 <filename>ghc/compiler</filename> is considered a leaf
2553 <filename>Makefile</filename> even though the
2554 <filename>ghc/compiler</filename> has sub-directories, because
2555 these sub-directories do not themselves have
2556 <filename>Makefile</filename>s in them. They are just used to
2557 structure the collection of modules that make up GHC, but all
2558 are managed by the single <filename>Makefile</filename> in
2559 <filename>ghc/compiler</filename>.</para>
2561 <para>You will notice that <filename>ghc/</filename> also
2562 contains a directory <filename>ghc/mk/</filename>. It contains
2563 GHC-specific <filename>Makefile</filename> boilerplate code.
2564 More precisely:</para>
2568 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2569 at the top of <filename>ghc/Makefile</filename>, and of all
2570 the leaf <filename>Makefile</filename>s in the
2571 sub-directories. It in turn <literal>include</literal>s the
2572 main boilerplate file
2573 <filename>mk/boilerplate.mk</filename>.</para>
2577 <para><filename>ghc/mk/target.mk</filename> is
2578 <literal>include</literal>d at the bottom of
2579 <filename>ghc/Makefile</filename>, and of all the leaf
2580 <filename>Makefile</filename>s in the sub-directories. It
2581 in turn <literal>include</literal>s the file
2582 <filename>mk/target.mk</filename>.</para>
2586 <para>So these two files are the place to look for GHC-wide
2587 customisation of the standard boilerplate.</para>
2590 <sect2 id="sec-boiler-arch">
2591 <title>Boilerplate architecture</title>
2592 <indexterm><primary>boilerplate architecture</primary></indexterm>
2594 <para>Every <filename>Makefile</filename> includes a
2595 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2596 file at the top, and
2597 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2598 file at the bottom. In this section we discuss what is in these
2599 files, and why there have to be two of them. In general:</para>
2603 <para><filename>boilerplate.mk</filename> consists of:</para>
2607 <para><emphasis>Definitions of millions of
2608 <command>make</command> variables</emphasis> that
2609 collectively specify the build configuration. Examples:
2610 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2611 the options to feed to the Haskell compiler;
2612 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2613 the sub-directories to enable within the
2614 <literal>nofib</literal> project;
2615 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2616 the name of the Haskell compiler to use when compiling
2617 GHC in the <literal>ghc</literal> project.</para>
2621 <para><emphasis>Standard pattern rules</emphasis> that
2622 tell <command>gmake</command> how to construct one file
2623 from another.</para>
2627 <para><filename>boilerplate.mk</filename> needs to be
2628 <literal>include</literal>d at the <emphasis>top</emphasis>
2629 of each <filename>Makefile</filename>, so that the user can
2630 replace the boilerplate definitions or pattern rules by
2631 simply giving a new definition or pattern rule in the
2632 <filename>Makefile</filename>. <command>gmake</command>
2633 simply takes the last definition as the definitive one.</para>
2635 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2636 definitions, it is also quite common to
2637 <emphasis>augment</emphasis> them. For example, a
2638 <filename>Makefile</filename> might say:</para>
2644 <para>thereby adding “<option>-O</option>” to
2646 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2650 <para><filename>target.mk</filename> contains
2651 <command>make</command> rules for the standard targets
2652 described in <Xref LinkEnd="sec-standard-targets">. These
2653 rules are selectively included, depending on the setting of
2654 certain <command>make</command> variables. These variables
2655 are usually set in the middle section of the
2656 <filename>Makefile</filename> between the two
2657 <literal>include</literal>s.</para>
2659 <para><filename>target.mk</filename> must be included at the
2660 end (rather than being part of
2661 <filename>boilerplate.mk</filename>) for several tiresome
2667 <para><command>gmake</command> commits target and
2668 dependency lists earlier than it should. For example,
2669 <FIlename>target.mk</FIlename> has a rule that looks
2673 $(HS_PROG) : $(OBJS)
2674 $(HC) $(LD_OPTS) $< -o $@
2677 <para>If this rule was in
2678 <filename>boilerplate.mk</filename> then
2679 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2681 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2682 would not have their final values at the moment
2683 <command>gmake</command> encountered the rule. Alas,
2684 <command>gmake</command> takes a snapshot of their
2685 current values, and wires that snapshot into the rule.
2686 (In contrast, the commands executed when the rule
2687 “fires” are only substituted at the moment
2688 of firing.) So, the rule must follow the definitions
2689 given in the <filename>Makefile</filename> itself.</para>
2693 <para>Unlike pattern rules, ordinary rules cannot be
2694 overriden or replaced by subsequent rules for the same
2695 target (at least, not without an error message).
2696 Including ordinary rules in
2697 <filename>boilerplate.mk</filename> would prevent the
2698 user from writing rules for specific targets in specific
2703 <para>There are a couple of other reasons I've
2704 forgotten, but it doesn't matter too much.</para>
2711 <sect2 id="sec-boiler">
2712 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2713 <indexterm><primary>boilerplate.mk</primary></indexterm>
2715 <para>If you look at
2716 <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
2717 you will find that it consists of the following sections, each
2718 held in a separate file:</para>
2722 <term><filename>config.mk</filename></term>
2723 <indexterm><primary>config.mk</primary></indexterm>
2725 <para>is the build configuration file we discussed at
2726 length in <Xref LinkEnd="sec-build-config">.</para>
2731 <term><filename>paths.mk</filename></term>
2732 <indexterm><primary>paths.mk</primary></indexterm>
2734 <para>defines <command>make</command> variables for
2735 pathnames and file lists. This file contains code for
2736 automatically compiling lists of source files and deriving
2737 lists of object files from those. The results can be
2738 overriden in the <filename>Makefile</filename>, but in
2739 most cases the automatic setup should do the right
2742 <para>The following variables may be set in the
2743 <filename>Makefile</filename> to affect how the automatic
2744 source file search is done:</para>
2748 <term><literal>ALL_DIRS</literal></term>
2749 <indexterm><primary><literal>ALL_DIRS</literal></primary>
2752 <para>Set to a list of directories to search in
2753 addition to the current directory for source
2759 <term><literal>EXCLUDE_SRCS</literal></term>
2760 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2763 <para>Set to a list of source files (relative to the
2764 current directory) to omit from the automatic
2765 search. The source searching machinery is clever
2766 enough to know that if you exclude a source file
2767 from which other sources are derived, then the
2768 derived sources should also be excluded. For
2769 example, if you set <literal>EXCLUDED_SRCS</literal>
2770 to include <filename>Foo.y</filename>, then
2771 <filename>Foo.hs</filename> will also be
2777 <term><literal>EXTRA_SRCS</literal></term>
2778 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2781 <para>Set to a list of extra source files (perhaps
2782 in directories not listed in
2783 <literal>ALL_DIRS</literal>) that should be
2789 <para>The results of the automatic source file search are
2790 placed in the following make variables:</para>
2794 <term><literal>SRCS</literal></term>
2795 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2797 <para>All source files found, sorted and without
2798 duplicates, including those which might not exist
2799 yet but will be derived from other existing sources.
2800 <literal>SRCS</literal> <emphasis>can</emphasis> be
2801 overriden if necessary, in which case the variables
2802 below will follow suit.</para>
2807 <term><literal>HS_SRCS</literal></term>
2808 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2810 <para>all Haskell source files in the current
2811 directory, including those derived from other source
2812 files (eg. Happy sources also give rise to Haskell
2818 <term><literal>HS_OBJS</literal></term>
2819 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2821 <para>Object files derived from
2822 <literal>HS_SRCS</literal>.</para>
2827 <term><literal>HS_IFACES</literal></term>
2828 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2830 <para>Interface files (<literal>.hi</literal> files)
2831 derived from <literal>HS_SRCS</literal>.</para>
2836 <term><literal>C_SRCS</literal></term>
2837 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2839 <para>All C source files found.</para>
2844 <term><literal>C_OBJS</literal></term>
2845 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2847 <para>Object files derived from
2848 <literal>C_SRCS</literal>.</para>
2853 <term><literal>SCRIPT_SRCS</literal></term>
2854 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2856 <para>All script source files found
2857 (<literal>.lprl</literal> files).</para>
2862 <term><literal>SCRIPT_OBJS</literal></term>
2863 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2865 <para><quote>object</quote> files derived from
2866 <literal>SCRIPT_SRCS</literal>
2867 (<literal>.prl</literal> files).</para>
2872 <term><literal>HSC_SRCS</literal></term>
2873 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2875 <para>All <literal>hsc2hs</literal> source files
2876 (<literal>.hsc</literal> files).</para>
2881 <term><literal>HAPPY_SRCS</literal></term>
2882 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2884 <para>All <literal>happy</literal> source files
2885 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2890 <term><literal>OBJS</literal></term>
2891 <indexterm><primary>OBJS</primary></indexterm>
2893 <para>the concatenation of
2894 <literal>$(HS_OBJS)</literal>,
2895 <literal>$(C_OBJS)</literal>, and
2896 <literal>$(SCRIPT_OBJS)</literal>.</para>
2901 <para>Any or all of these definitions can easily be
2902 overriden by giving new definitions in your
2903 <filename>Makefile</filename>.</para>
2905 <para>What, exactly, does <filename>paths.mk</filename>
2906 consider a <quote>source file</quote> to be? It's based
2907 on the file's suffix (e.g. <filename>.hs</filename>,
2908 <filename>.lhs</filename>, <filename>.c</filename>,
2909 <filename>.hy</filename>, etc), but this is the kind of
2910 detail that changes, so rather than enumerate the source
2911 suffices here the best thing to do is to look in
2912 <filename>paths.mk</filename>.</para>
2917 <term><filename>opts.mk</filename></term>
2918 <indexterm><primary>opts.mk</primary></indexterm>
2920 <para>defines <command>make</command> variables for option
2921 strings to pass to each program. For example, it defines
2922 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2923 the option strings to pass to the Haskell compiler. See
2924 <Xref LinkEnd="sec-suffix">.</para>
2929 <term><filename>suffix.mk</filename></term>
2930 <indexterm><primary>suffix.mk</primary></indexterm>
2932 <para>defines standard pattern rules—see <Xref
2933 LinkEnd="sec-suffix">.</para>
2938 <para>Any of the variables and pattern rules defined by the
2939 boilerplate file can easily be overridden in any particular
2940 <filename>Makefile</filename>, because the boilerplate
2941 <literal>include</literal> comes first. Definitions after this
2942 <literal>include</literal> directive simply override the default
2943 ones in <filename>boilerplate.mk</filename>.</para>
2946 <sect2 id="sec-suffix">
2947 <title>Pattern rules and options</title>
2948 <indexterm><primary>Pattern rules</primary></indexterm>
2951 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2952 defines standard <emphasis>pattern rules</emphasis> that say how
2953 to build one kind of file from another, for example, how to
2954 build a <filename>.o</filename> file from a
2955 <filename>.c</filename> file. (GNU <command>make</command>'s
2956 <emphasis>pattern rules</emphasis> are more powerful and easier
2957 to use than Unix <command>make</command>'s <emphasis>suffix
2958 rules</emphasis>.)</para>
2960 <para>Almost all the rules look something like this:</para>
2965 $(CC) $(CC_OPTS) -c $< -o $@
2968 <para>Here's how to understand the rule. It says that
2969 <emphasis>something</emphasis><filename>.o</filename> (say
2970 <filename>Foo.o</filename>) can be built from
2971 <emphasis>something</emphasis><filename>.c</filename>
2972 (<filename>Foo.c</filename>), by invoking the C compiler (path
2973 name held in <constant>$(CC)</constant>), passing to it
2974 the options <constant>$(CC_OPTS)</constant> and
2975 the rule's dependent file of the rule
2976 <literal>$<</literal> (<filename>Foo.c</filename> in
2977 this case), and putting the result in the rule's target
2978 <literal>$@</literal> (<filename>Foo.o</filename> in this
2981 <para>Every program is held in a <command>make</command>
2982 variable defined in <filename>mk/config.mk</filename>—look
2983 in <filename>mk/config.mk</filename> for the complete list. One
2984 important one is the Haskell compiler, which is called
2985 <constant>$(HC)</constant>.</para>
2987 <para>Every program's options are are held in a
2988 <command>make</command> variables called
2989 <constant><prog>_OPTS</constant>. the
2990 <constant><prog>_OPTS</constant> variables are
2991 defined in <filename>mk/opts.mk</filename>. Almost all of them
2992 are defined like this:</para>
2995 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
2998 <para>The four variables from which
2999 <constant>CC_OPTS</constant> is built have the following
3004 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3006 <para>options passed to all C compilations.</para>
3011 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3013 <para>options passed to C compilations for way
3014 <literal><way></literal>. For example,
3015 <constant>WAY_mp_CC_OPTS</constant>
3016 gives options to pass to the C compiler when compiling way
3017 <literal>mp</literal>. The variable
3018 <constant>WAY_CC_OPTS</constant> holds
3019 options to pass to the C compiler when compiling the
3020 standard way. (<Xref LinkEnd="sec-ways"> dicusses
3021 multi-way compilation.)</para>
3026 <term><constant><module>_CC_OPTS</constant>:</term>
3028 <para>options to pass to the C compiler that are specific
3029 to module <literal><module></literal>. For example,
3030 <constant>SMap_CC_OPTS</constant> gives the
3031 specific options to pass to the C compiler when compiling
3032 <filename>SMap.c</filename>.</para>
3037 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3039 <para>extra options to pass to all C compilations. This
3040 is intended for command line use, thus:</para>
3043 gmake libHS.a EXTRA_CC_OPTS="-v"
3050 <sect2 id="sec-targets">
3051 <title>The main <filename>mk/target.mk</filename> file</title>
3052 <indexterm><primary>target.mk</primary></indexterm>
3054 <para><filename>target.mk</filename> contains canned rules for
3055 all the standard targets described in <Xref
3056 LinkEnd="sec-standard-targets">. It is complicated by the fact
3057 that you don't want all of these rules to be active in every
3058 <filename>Makefile</filename>. Rather than have a plethora of
3059 tiny files which you can include selectively, there is a single
3060 file, <filename>target.mk</filename>, which selectively includes
3061 rules based on whether you have defined certain variables in
3062 your <filename>Makefile</filename>. This section explains what
3063 rules you get, what variables control them, and what the rules
3064 do. Hopefully, you will also get enough of an idea of what is
3065 supposed to happen that you can read and understand any weird
3066 special cases yourself.</para>
3070 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3072 <para>If <constant>HS_PROG</constant> is defined,
3073 you get rules with the following targets:</para>
3077 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3079 <para>itself. This rule links
3080 <constant>$(OBJS)</constant> with the Haskell
3081 runtime system to get an executable called
3082 <constant>$(HS_PROG)</constant>.</para>
3087 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3090 <constant>$(HS_PROG)</constant> in
3091 <constant>$(bindir)</constant>.</para>
3100 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3102 <para>is similar to <constant>HS_PROG</constant>,
3103 except that the link step links
3104 <constant>$(C_OBJS)</constant> with the C
3105 runtime system.</para>
3110 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3112 <para>is similar to <constant>HS_PROG</constant>,
3113 except that it links
3114 <constant>$(LIB_OBJS)</constant> to make the
3115 library archive <constant>$(LIBRARY)</constant>,
3116 and <literal>install</literal> installs it in
3117 <constant>$(libdir)</constant>.</para>
3122 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3124 <para>…</para>
3129 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3131 <para>…</para>
3136 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3138 <para>If <constant>HS_SRCS</constant> is defined
3139 and non-empty, a rule for the target
3140 <literal>depend</literal> is included, which generates
3141 dependency information for Haskell programs. Similarly
3142 for <constant>C_SRCS</constant>.</para>
3147 <para>All of these rules are “double-colon” rules,
3151 install :: $(HS_PROG)
3152 ...how to install it...
3155 <para>GNU <command>make</command> treats double-colon rules as
3156 separate entities. If there are several double-colon rules for
3157 the same target it takes each in turn and fires it if its
3158 dependencies say to do so. This means that you can, for
3159 example, define both <constant>HS_PROG</constant> and
3160 <constant>LIBRARY</constant>, which will generate two rules for
3161 <literal>install</literal>. When you type <command>gmake
3162 install</command> both rules will be fired, and both the program
3163 and the library will be installed, just as you wanted.</para>
3166 <sect2 id="sec-subdirs">
3167 <title>Recursion</title>
3168 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3169 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3171 <para>In leaf <filename>Makefile</filename>s the variable
3172 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3173 is undefined. In non-leaf <filename>Makefile</filename>s,
3174 <constant>SUBDIRS</constant> is set to the list of
3175 sub-directories that contain subordinate
3176 <filename>Makefile</filename>s. <emphasis>It is up to you to
3177 set <constant>SUBDIRS</constant> in the
3178 <filename>Makefile</filename>.</emphasis> There is no automation
3179 here—<constant>SUBDIRS</constant> is too important to
3182 <para>When <constant>SUBDIRS</constant> is defined,
3183 <filename>target.mk</filename> includes a rather neat rule for
3184 the standard targets (<Xref LinkEnd="sec-standard-targets"> that
3185 simply invokes <command>make</command> recursively in each of
3186 the sub-directories.</para>
3188 <para><emphasis>These recursive invocations are guaranteed to
3189 occur in the order in which the list of directories is specified
3190 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3191 be important. For example, when you say <command>gmake
3192 boot</command> it can be important that the recursive invocation
3193 of <command>make boot</command> is done in one sub-directory
3194 (the include files, say) before another (the source files).
3195 Generally, put the most independent sub-directory first, and the
3196 most dependent last.</para>
3199 <sect2 id="sec-ways">
3200 <title>Way management</title>
3201 <indexterm><primary>way management</primary></indexterm>
3203 <para>We sometimes want to build essentially the same system in
3204 several different “ways”. For example, we want to build GHC's
3205 <literal>Prelude</literal> libraries with and without profiling,
3206 so that there is an appropriately-built library archive to link
3207 with when the user compiles his program. It would be possible
3208 to have a completely separate build tree for each such “way”,
3209 but it would be horribly bureaucratic, especially since often
3210 only parts of the build tree need to be constructed in multiple
3214 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3215 contains some clever magic to allow you to build several
3216 versions of a system; and to control locally how many versions
3217 are built and how they differ. This section explains the
3220 <para>The files for a particular way are distinguished by
3221 munging the suffix. The <quote>normal way</quote> is always
3222 built, and its files have the standard suffices
3223 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3224 In addition, you can build one or more extra ways, each
3225 distinguished by a <emphasis>way tag</emphasis>. The object
3226 files and interface files for one of these extra ways are
3227 distinguished by their suffix. For example, way
3228 <literal>mp</literal> has files
3229 <filename>.mp_o</filename> and
3230 <filename>.mp_hi</filename>. Library archives have their
3231 way tag the other side of the dot, for boring reasons; thus,
3232 <filename>libHS_mp.a</filename>.</para>
3234 <para>A <command>make</command> variable called
3235 <constant>way</constant> holds the current way tag.
3236 <emphasis><constant>way</constant> is only ever set on the
3237 command line of <command>gmake</command></emphasis> (usually in
3238 a recursive invocation of <command>gmake</command> by the
3239 system). It is never set inside a
3240 <filename>Makefile</filename>. So it is a global constant for
3241 any one invocation of <command>gmake</command>. Two other
3242 <command>make</command> variables,
3243 <constant>way_</constant> and
3244 <constant>_way</constant> are immediately derived from
3245 <constant>$(way)</constant> and never altered. If
3246 <constant>way</constant> is not set, then neither are
3247 <constant>way_</constant> and
3248 <constant>_way</constant>, and the invocation of
3249 <command>make</command> will build the <quote>normal
3250 way</quote>. If <constant>way</constant> is set, then the other
3251 two variables are set in sympathy. For example, if
3252 <constant>$(way)</constant> is “<literal>mp</literal>”,
3253 then <constant>way_</constant> is set to
3254 “<literal>mp_</literal>” and
3255 <constant>_way</constant> is set to
3256 “<literal>_mp</literal>”. These three variables are
3257 then used when constructing file names.</para>
3259 <para>So how does <command>make</command> ever get recursively
3260 invoked with <constant>way</constant> set? There are two ways
3261 in which this happens:</para>
3265 <para>For some (but not all) of the standard targets, when
3266 in a leaf sub-directory, <command>make</command> is
3267 recursively invoked for each way tag in
3268 <constant>$(WAYS)</constant>. You set
3269 <constant>WAYS</constant> in the
3270 <filename>Makefile</filename> to the list of way tags you
3271 want these targets built for. The mechanism here is very
3272 much like the recursive invocation of
3273 <command>make</command> in sub-directories (<Xref
3274 LinkEnd="sec-subdirs">). It is up to you to set
3275 <constant>WAYS</constant> in your
3276 <filename>Makefile</filename>; this is how you control what
3277 ways will get built.</para>
3281 <para>For a useful collection of targets (such as
3282 <filename>libHS_mp.a</filename>,
3283 <filename>Foo.mp_o</filename>) there is a rule which
3284 recursively invokes <command>make</command> to make the
3285 specified target, setting the <constant>way</constant>
3286 variable. So if you say <command>gmake
3287 Foo.mp_o</command> you should see a recursive
3288 invocation <command>gmake Foo.mp_o way=mp</command>,
3289 and <emphasis>in this recursive invocation the pattern rule
3290 for compiling a Haskell file into a <filename>.o</filename>
3291 file will match</emphasis>. The key pattern rules (in
3292 <filename>suffix.mk</filename>) look like this:
3296 $(HC) $(HC_OPTS) $< -o $@
3303 <para>You can invoke <command>make</command> with a
3304 particular <literal>way</literal> setting yourself, in order
3305 to build files related to a particular
3306 <literal>way</literal> in the current directory. eg.
3312 will build files for the profiling way only in the current
3319 <title>When the canned rule isn't right</title>
3321 <para>Sometimes the canned rule just doesn't do the right thing.
3322 For example, in the <literal>nofib</literal> suite we want the
3323 link step to print out timing information. The thing to do here
3324 is <emphasis>not</emphasis> to define
3325 <constant>HS_PROG</constant> or
3326 <constant>C_PROG</constant>, and instead define a special
3327 purpose rule in your own <filename>Makefile</filename>. By
3328 using different variable names you will avoid the canned rules
3329 being included, and conflicting with yours.</para>
3333 <sect1 id="building-docs">
3334 <title>Building the documentation</title>
3336 <sect2 id="pre-supposed-doc-tools">
3337 <title>Tools for building the Documentation</title>
3339 <para>The following additional tools are required if you want to
3340 format the documentation that comes with the
3341 <literal>fptools</literal> projects:</para>
3345 <term>DocBook</term>
3346 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3347 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3349 <para>Much of our documentation is written in SGML, using
3350 the DocBook DTD. Instructions on installing and
3351 configuring the DocBook tools are below.</para>
3357 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3358 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3360 <para>A decent TeX distribution is required if you want to
3361 produce printable documentation. We recomment teTeX,
3362 which includes just about everything you need.</para>
3367 <term>Haddock</term>
3368 <indexterm><primary>Haddock</primary>
3371 <para>Haddock is a Haskell documentation tool that we use
3372 for automatically generating documentation from the
3373 library source code. It is an <literal>fptools</literal>
3374 project in itself. To build documentation for the
3375 libraries (<literal>fptools/libraries</literal>) you
3376 should check out and build Haddock in
3377 <literal>fptools/haddock</literal>. Haddock requires GHC
3385 <title>Installing the DocBook tools</title>
3388 <title>Installing the DocBook tools on Linux</title>
3390 <para>If you're on a recent RedHat system (7.0+), you probably
3391 have working DocBook tools already installed. The configure
3392 script should detect your setup and you're away.</para>
3394 <para>If you don't have DocBook tools installed, and you are
3395 using a system that can handle RedHat RPM packages, you can
3396 probably use the <ULink
3397 URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3398 DocBook tools</ULink>, which is the most shrink-wrapped SGML
3399 suite that we could find. You need all the RPMs except for
3400 psgml (i.e. <Filename>docbook</Filename>,
3401 <Filename>jade</Filename>, <Filename>jadetex</Filename>,
3402 <Filename>sgmlcommon</Filename> and
3403 <Filename>stylesheets</Filename>). Note that most of these
3404 RPMs are architecture neutral, so are likely to be found in a
3405 <Filename>noarch</Filename> directory. The SuSE RPMs also
3406 work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
3407 (7.0 and later should be OK), but they are easy to fix: just
3409 <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
3410 to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
3414 <title>Installing DocBook on FreeBSD</title>
3416 <para>On FreeBSD systems, the easiest way to get DocBook up
3417 and running is to install it from the ports tree or a
3418 pre-compiled package (packages are available from your local
3419 FreeBSD mirror site).</para>
3421 <para>To use the ports tree, do this:
3423 $ cd /usr/ports/textproc/docproj
3426 This installs the FreeBSD documentation project tools, which
3427 includes everything needed to format the GHC
3428 documentation.</para>
3432 <title>Installing from binaries on Windows</title>
3434 <Para>It's a good idea to use Norman Walsh's <ULink
3435 URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3436 notes</ULink> as a guide. You should get version 3.1 of
3437 DocBook, and note that his file <Filename>test.sgm</Filename>
3438 won't work, as it needs version 3.0. You should unpack Jade
3439 into <Filename>\Jade</Filename>, along with the entities,
3440 DocBook into <Filename>\docbook</Filename>, and the DocBook
3441 stylesheets into <Filename>\docbook\stylesheets</Filename> (so
3442 they actually end up in
3443 <Filename>\docbook\stylesheets\docbook</Filename>).</para>
3448 <title>Installing the DocBook tools from source</title>
3453 <para>Install <ULink
3454 URL="http://openjade.sourceforge.net/">OpenJade</ULink>
3455 (Windows binaries are available as well as sources). If you
3456 want DVI, PS, or PDF then install JadeTeX from the
3457 <Filename>dsssl</Filename> subdirectory. (If you get the
3461 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
3464 your version of <Command>hyperref</Command> is out of date;
3465 download it from CTAN
3466 (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
3467 and make it, ensuring that you have first removed or renamed
3468 your old copy. If you start getting file not found errors
3469 when making the test for <Command>hyperref</Command>, you
3470 can abort at that point and proceed straight to
3471 <Command>make install</Command>, or enter them as
3472 <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
3474 <para>Make links from <Filename>virtex</Filename> to
3475 <Filename>jadetex</Filename> and
3476 <Filename>pdfvirtex</Filename> to
3477 <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
3478 and PDF output will not work). Copy
3479 <Filename>dsssl/*.{dtd,dsl}</Filename> and
3480 <Filename>catalog</Filename> to
3481 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3485 <title>DocBook and the DocBook stylesheets</title>
3487 <para>Get a Zip of <ULink
3488 URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
3489 and install the contents in
3490 <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
3492 <para>Get the <ULink
3493 URL="http://nwalsh.com/docbook/dsssl/">DocBook
3494 stylesheets</ULink> and install in
3495 <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
3496 (thereby creating a subdirectory docbook). For indexing,
3497 copy or link <Filename>collateindex.pl</Filename> from the
3498 DocBook stylesheets archive in <Filename>bin</Filename> into
3499 a directory on your <Constant>PATH</Constant>.</para>
3501 <para>Download the <ULink
3502 URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3503 entities</ULink> into
3504 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3510 <title>Configuring the DocBook tools</title>
3512 <Para>Once the DocBook tools are installed, the configure script
3513 will detect them and set up the build system accordingly. If you
3514 have a system that isn't supported, let us know, and we'll try
3519 <title>Remaining problems</title>
3521 <para>If you install from source, you'll get a pile of warnings
3524 <Screen>DTDDECL catalog entries are not supported</Screen>
3526 every time you build anything. These can safely be ignored, but
3527 if you find them tedious you can get rid of them by removing all
3528 the <Constant>DTDDECL</Constant> entries from
3529 <Filename>docbook.cat</Filename>.</para>
3533 <title>Building the documentation</title>
3535 <para>To build documentation in a certain format, you can
3536 say, for example,</para>
3542 <para>to build HTML documentation below the current directory.
3543 The available formats are: <literal>dvi</literal>,
3544 <literal>ps</literal>, <literal>pdf</literal>,
3545 <literal>html</literal>, and <literal>rtf</literal>. Note that
3546 not all documentation can be built in all of these formats: HTML
3547 documentation is generally supported everywhere, and DocBook
3548 documentation might support the other formats (depending on what
3549 other tools you have installed).</para>
3551 <para>All of these targets are recursive; that is, saying
3552 <literal>make html</literal> will make HTML docs for all the
3553 documents recursively below the current directory.</para>
3555 <para>Because there are many different formats that the DocBook
3556 documentation can be generated in, you have to select which ones
3557 you want by setting the <literal>SGMLDocWays</literal> variable
3558 to a list of them. For example, in
3559 <filename>build.mk</filename> you might have a line:</para>
3562 SGMLDocWays = html ps
3565 <para>This will cause the documentation to be built in the requested
3566 formats as part of the main build (the default is not to build
3567 any documentation at all).</para>
3571 <title>Installing the documentation</title>
3573 <para>To install the documentation, use:</para>
3579 <para>This will install the documentation into
3580 <literal>$(datadir)</literal> (which defaults to
3581 <literal>$(prefix)/share</literal>). The exception is HTML
3582 documentation, which goes into
3583 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3585 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3586 to a list of formats, the <literal>install-docs</literal> target
3587 won't do anything for SGML documentation.</para>
3593 <sect1 id="sec-porting-ghc">
3594 <title>Porting GHC</title>
3596 <para>This section describes how to port GHC to a currenly
3597 unsupported platform. There are two distinct
3598 possibilities:</para>
3602 <para>The hardware architecture for your system is already
3603 supported by GHC, but you're running an OS that isn't
3604 supported (or perhaps has been supported in the past, but
3605 currently isn't). This is the easiest type of porting job,
3606 but it still requires some careful bootstrapping. Proceed to
3607 <xref linkend="sec-booting-from-hc">.</para>
3611 <para>Your system's hardware architecture isn't supported by
3612 GHC. This will be a more difficult port (though by comparison
3613 perhaps not as difficult as porting gcc). Proceed to <xref
3614 linkend="unregisterised-porting">.</para>
3618 <sect2 id="sec-booting-from-hc">
3619 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3621 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3622 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3623 <indexterm><primary>porting GHC</primary></indexterm>
3625 <para>Bootstrapping GHC on a system without GHC already
3626 installed is achieved by taking the intermediate C files (known
3627 as HC files) from a GHC compilation on a supported system to the
3628 target machine, and compiling them using gcc to get a working
3631 <para><emphasis>NOTE: GHC versions 5.xx and later are
3632 significantly harder to bootstrap from C than earlier versions.
3633 We recommend starting from version 4.08.2 if you need to
3634 bootstrap in this way.</emphasis></para>
3636 <para>HC files are architecture-dependent (but not
3637 OS-dependent), so you have to get a set that were generated on
3638 similar hardware. There may be some supplied on the GHC
3639 download page, otherwise you'll have to compile some up
3640 yourself, or start from <emphasis>unregisterised</emphasis> HC
3641 files - see <xref linkend="unregisterised-porting">.</para>
3643 <para>The following steps should result in a working GHC build
3644 with full libraries:</para>
3648 <para>Unpack the HC files on top of a fresh source tree
3649 (make sure the source tree version matches the version of
3650 the HC files <emphasis>exactly</emphasis>!). This will
3651 place matching <filename>.hc</filename> files next to the
3652 corresponding Haskell source (<filename>.hs</filename> or
3653 <filename>.lhs</filename>) in the compiler subdirectory
3654 <filename>ghc/compiler</filename> and in the libraries
3655 (subdirectories of <filename>hslibs</filename> and
3656 <literal>libraries</literal>).</para>
3660 <para>The actual build process is fully automated by the
3661 <filename>hc-build</filename> script located in the
3662 <filename>distrib</filename> directory. If you eventually
3663 want to install GHC into the directory
3664 <replaceable>dir</replaceable>, the following
3665 command will execute the whole build process (it won't
3666 install yet):</para>
3669 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3671 <indexterm><primary>--hc-build</primary></indexterm>
3673 <para>By default, the installation directory is
3674 <filename>/usr/local</filename>. If that is what you want,
3675 you may omit the argument to <filename>hc-build</filename>.
3676 Generally, any option given to <filename>hc-build</filename>
3677 is passed through to the configuration script
3678 <filename>configure</filename>. If
3679 <filename>hc-build</filename> successfully completes the
3680 build process, you can install the resulting system, as
3690 <sect2 id="unregisterised-porting">
3691 <title>Porting GHC to a new architecture</title>
3693 <para>The first step in porting to a new architecture is to get
3694 an <firstterm>unregisterised</firstterm> build working. An
3695 unregisterised build is one that compiles via vanilla C only.
3696 By contrast, a registerised build uses the following
3697 architecture-specific hacks for speed:</para>
3701 <para>Global register variables: certain abstract machine
3702 <quote>registers</quote> are mapped to real machine
3703 registers, depending on how many machine registers are
3705 <filename>ghc/includes/MachRegs.h</filename>).</para>
3709 <para>Assembly-mangling: when compiling via C, we feed the
3710 assembly generated by gcc though a Perl script known as the
3711 <firstterm>mangler</firstterm> (see
3712 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3713 mangler rearranges the assembly to support tail-calls and
3714 various other optimisations.</para>
3718 <para>In an unregisterised build, neither of these hacks are
3719 used — the idea is that the C code generated by the
3720 compiler should compile using gcc only. The lack of these
3721 optimisations costs about a factor of two in performance, but
3722 since unregisterised compilation is usually just a step on the
3723 way to a full registerised port, we don't mind too much.</para>
3726 <title>Building an unregisterised port</title>
3728 <para>The first step is to get some unregisterised HC files.
3729 Either (a) download them from the GHC site (if there are
3730 some available for the right version of GHC), or
3731 (b) build them yourself on any machine with a working
3732 GHC. If at all possible this should be a machine with the
3733 same word size as the target.</para>
3735 <para>There is a script available which should automate the
3736 process of doing the 2-stage bootstrap necessary to get the
3737 unregisterised HC files - it's available in <ulink
3738 url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
3741 <para>Now take these unregisterised HC files to the target
3742 platform and bootstrap a compiler from them as per the
3743 instructions in <xref linkend="sec-booting-from-hc">. In
3744 <filename>build.mk</filename>, you need to tell the build
3745 system that the compiler you're building is
3746 (a) unregisterised itself, and (b) builds
3747 unregisterised binaries. This varies depending on the GHC
3748 version you're bootstraping:</para>
3751 # build.mk for GHC 4.08.x
3752 GhcWithRegisterised=NO
3756 # build.mk for GHC 5.xx and 6.x
3757 GhcUnregisterised=YES
3760 <para>Versions 5.xx and 6.x only: use the option
3761 <option>--enable-hc-boot-unregisterised</option> instead of
3762 <option>--enable-hc-boot</option> when running
3763 <filename>./configure</filename>.</para>
3765 <para>The build may not go through cleanly. We've tried to
3766 stick to writing portable code in most parts of the compiler,
3767 so it should compile on any POSIXish system with gcc, but in
3768 our experience most systems differ from the standards in one
3769 way or another. Deal with any problems as they arise - if you
3770 get stuck, ask the experts on
3771 <email>glasgow-haskell-users@haskell.org</email>.</para>
3773 <para>Once you have the unregisterised compiler up and
3774 running, you can use it to start a registerised port. The
3775 following sections describe the various parts of the system
3776 that will need architecture-specific tweaks in order to get a
3777 registerised build going.</para>
3779 <para>Lots of useful information about the innards of GHC is
3780 available in the <ulink
3781 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3782 Commentary</ulink>, which might be helpful if you run into
3783 some code which needs tweaking for your system.</para>
3787 <title>Porting the RTS</title>
3789 <para>The following files need architecture-specific code for a
3790 registerised build:</para>
3794 <term><filename>ghc/includes/MachRegs.h</filename></term>
3795 <indexterm><primary><filename>MachRegs.h</filename></primary>
3798 <para>Defines the STG-register to machine-register
3799 mapping. You need to know your platform's C calling
3800 convention, and which registers are generally available
3801 for mapping to global register variables. There are
3802 plenty of useful comments in this file.</para>
3806 <term><filename>ghc/includes/TailCalls.h</filename></term>
3807 <indexterm><primary><filename>TailCalls.h</filename></primary>
3810 <para>Macros that cooperate with the mangler (see <xref
3811 linkend="sec-mangler">) to make proper tail-calls
3816 <term><filename>ghc/rts/Adjustor.c</filename></term>
3817 <indexterm><primary><filename>Adjustor.c</filename></primary>
3821 <literal>foreign import "wrapper"</literal>
3823 <literal>foreign export dynamic</literal>).
3824 Not essential for getting GHC bootstrapped, so this file
3825 can be deferred until later if necessary.</para>
3829 <term><filename>ghc/rts/StgCRun.c</filename></term>
3830 <indexterm><primary><filename>StgCRun.c</filename></primary>
3833 <para>The little assembly layer between the C world and
3834 the Haskell world. See the comments and code for the
3835 other architectures in this file for pointers.</para>
3839 <term><filename>ghc/rts/MBlock.h</filename></term>
3840 <term><filename>ghc/rts/MBlock.c</filename></term>
3841 <indexterm><primary><filename>MBlock.h</filename></primary>
3843 <indexterm><primary><filename>MBlock.c</filename></primary>
3846 <para>These files are really OS-specific rather than
3847 architecture-specific. In <filename>MBlock.h</filename>
3848 is specified the absolute location at which the RTS
3849 should try to allocate memory on your platform (try to
3850 find an area which doesn't conflict with code or dynamic
3851 libraries). In <filename>Mblock.c</filename> you might
3852 need to tweak the call to <literal>mmap()</literal> for
3859 <sect3 id="sec-mangler">
3860 <title>The mangler</title>
3862 <para>The mangler is an evil Perl-script that rearranges the
3863 assembly code output from gcc to do two main things:</para>
3867 <para>Remove function prologues and epilogues, and all
3868 movement of the C stack pointer. This is to support
3869 tail-calls: every code block in Haskell code ends in an
3870 explicit jump, so we don't want the C-stack overflowing
3871 while we're jumping around between code blocks.</para>
3874 <para>Move the <firstterm>info table</firstterm> for a
3875 closure next to the entry code for that closure. In
3876 unregisterised code, info tables contain a pointer to the
3877 entry code, but in registerised compilation we arrange
3878 that the info table is shoved right up against the entry
3879 code, and addressed backwards from the entry code pointer
3880 (this saves a word in the info table and an extra
3881 indirection when jumping to the closure entry
3886 <para>The mangler is abstracted to a certain extent over some
3887 architecture-specific things such as the particular assembler
3888 directives used to herald symbols. Take a look at the
3889 definitions for other architectures and use these as a
3890 starting point.</para>
3894 <title>The native code generator</title>
3896 <para>The native code generator isn't essential to getting a
3897 registerised build going, but it's a desirable thing to have
3898 because it can cut compilation times in half. The native code
3899 generator is described in some detail in the <ulink
3900 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3901 commentary</ulink>.</para>
3907 <para>To support GHCi, you need to port the dynamic linker
3908 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
3909 currently supports the ELF and PEi386 object file formats - if
3910 your platform uses one of these then you probably don't have
3911 to do anything except fiddle with the
3912 <literal>#ifdef</literal>s at the top of
3913 <filename>Linker.c</filename> to tell it about your OS.</para>
3915 <para>If your system uses a different object file format, then
3916 you have to write a linker — good luck!</para>
3922 <sect1 id="sec-build-pitfalls">
3923 <title>Known pitfalls in building Glasgow Haskell
3925 <indexterm><primary>problems, building</primary></indexterm>
3926 <indexterm><primary>pitfalls, in building</primary></indexterm>
3927 <indexterm><primary>building pitfalls</primary></indexterm></title>
3930 WARNINGS about pitfalls and known “problems”:
3939 One difficulty that comes up from time to time is running out of space
3940 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
3941 compensate for the vagaries of different sysadmin approaches to temp
3943 <indexterm><primary>tmp, running out of space in</primary></indexterm>
3945 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
3946 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
3949 The best way around it is to say
3952 export TMPDIR=<dir>
3955 in your <filename>build.mk</filename> file.
3956 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
3965 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
3966 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
3974 When compiling via C, you'll sometimes get “warning: assignment from
3975 incompatible pointer type” out of GCC. Harmless.
3982 Similarly, <command>ar</command>chiving warning messages like the following are not
3986 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
3987 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
3997 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
3998 get an “Out of heap space” error message. These can vary with the
3999 vagaries of different systems, it seems. The solution is simple:
4006 If you're compiling with GHC 4.00 or later, then the
4007 <emphasis>maximum</emphasis> heap size must have been reached. This
4008 is somewhat unlikely, since the maximum is set to 64M by default.
4009 Anyway, you can raise it with the
4010 <option>-optCrts-M<size></option> flag (add this flag to
4011 <constant><module>_HC_OPTS</constant>
4012 <command>make</command> variable in the appropriate
4013 <filename>Makefile</filename>).
4020 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4029 and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
4030 <constant><module>_HC_OPTS</constant>.)
4032 Alternatively, just cut to the chase:
4036 % make EXTRA_HC_OPTS=-optCrts-M128M
4045 If you try to compile some Haskell, and you get errors from GCC about
4046 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4047 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4049 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4050 this bug also suggests that you have an old GCC.
4058 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4062 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4063 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4065 ? # or, on some machines: ar s $i
4070 We'd be interested to know if this is still necessary.
4078 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4079 a bit from one Unix to another. One particular gotcha is macro calls
4084 SLIT("Hello, world")
4088 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4089 arguments, so you get
4093 :731: macro `SLIT' used with too many (2) args
4097 Alas, <command>cpp</command> doesn't tell you the offending file!
4099 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4110 <Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
4113 This section summarises how to get the utilities you need on your
4114 Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
4115 installing and running GHC may be found in the user guide. In general,
4116 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4117 You should read the GHC installation guide sections on Windows (in the user
4118 guide) before continuing to read these notes.
4122 <sect2 id="cygwin-and-mingw"><Title>Cygwin and MinGW</Title>
4124 <para> The Windows situation for building GHC is rather confusing. This section
4125 tries to clarify, and to establish terminology.</para>
4127 <sect3 id="ghc-mingw"><title>GHC-mingw</title>
4129 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4130 is a collection of header
4131 files and import libraries that allow one to use <command>gcc</command> and produce
4132 native Win32 programs that do not rely on any third-party DLLs. The
4133 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4134 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4137 <para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
4138 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4139 GHC compiles Haskell to C (or to
4140 assembly code), and then invokes these MinGW tools to generate an executable binary.
4141 The resulting binaries can run on any Win32 system.
4143 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4145 <para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
4146 Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
4147 library; they have to do
4148 their input output using standard Haskell I/O libraries, or native Win32 bindings.
4152 <sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
4154 <para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
4155 <ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
4156 Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
4157 <command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
4158 A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
4160 <para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
4161 Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
4162 A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
4163 If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
4164 that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
4165 Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4166 does not change, but the implementation certainly does. Even the interfaces to functions
4167 it exports seem to change occasionally. So programs compiled by GHC might only run with
4168 particular versions of Cygwin. All of this seems very undesirable.
4171 Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
4172 we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
4173 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4177 <sect3><title>HOST_OS vs TARGET_OS</title>
4180 In the source code you'll find various ifdefs looking like:
4182 #ifdef mingw32_HOST_OS
4188 #ifdef mingw32_TARGET_OS
4192 These macros are set by the configure script (via the file config.h).
4193 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4196 The "host" system is the one on which GHC itself will be run.
4199 The "target" system is the one for which the program compiled by GHC will be run.
4202 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4203 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4208 <sect3><title>Summary</title>
4210 <para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
4211 how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
4212 by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
4214 <para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
4215 GHC-cygwin too is beyond our resources. The GHC we distribute
4216 therefore does not require Cygwin to run, nor do the programs it
4217 compiles require Cygwin.</para>
4219 <para>The instructions that follow describe how to build GHC-mingw. It is
4220 possible to build GHC-cygwin, but it's not a supported route, and the build system might
4223 <para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>. It
4224 uses the <Command>gcc</Command> that you specify using the
4225 <option>--with-gcc</option> flag when you run
4226 <Command>configure</Command> (see below).
4227 The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
4228 to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
4229 whatever one happens to be in your path. However, the makefiles do use whatever <Command>ld</Command>
4230 and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
4231 used to glom together .o files into a bigger .o file, or a .a file,
4232 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4233 Cygwin and Mingw use the same .o file format. So its ok.
4238 <Sect2><Title>Installing and configuring Cygwin</Title>
4240 <para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
4241 but you do need it to <emphasis>build</emphasis> GHC.</para>
4243 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4244 The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
4245 During the installation dialogue, make sure that you select:
4246 <command>cvs</command>, <command>openssh</command>,
4247 <command>autoconf</command>,
4248 <command>binutils</command> (includes ld and (I think) ar),
4249 <command>gcc</command>,
4250 <command>flex</command>,
4251 <command>make</command>.
4254 <para> Now set the following user environment variables:
4257 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4258 <constant>PATH</constant></para></listitem>
4262 Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
4263 don't do this you get very weird messages when you type
4264 <Command>make</Command>, such as:
4266 /c: /c: No such file or directory
4271 <listitem><para> Set <constant>SHELL</constant> to
4272 <Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
4273 <constant>SHELL</constant> is what you get.
4276 <listitem><para> Set <constant>HOME</constant> to point to your
4277 home directory. This is where, for example,
4278 <command>bash</command> will look for your <filename>.bashrc</filename>
4279 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4285 There are a few other things to do:
4289 By default, cygwin provides the command shell <filename>ash</filename>
4290 as <filename>sh.exe</filename>. We have often seen build-system problems that
4291 turn out to be due to bugs in <filename>ash</filename>
4293 and length of command lines). On the other hand <filename>bash</filename> seems
4295 So, in <filename>cygwin/bin</filename>
4296 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4297 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4298 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4299 you can't rename a running program!
4305 Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
4306 (and similarly for <Command>sh</Command>). Notice the hardwired path!
4307 So you need to ensure that your <Filename>/bin</Filename> directory has the following
4310 <listitem> <para><Command>sh</Command></para></listitem>
4311 <listitem> <para><Command>perl</Command></para></listitem>
4312 <listitem> <para><Command>cat</Command></para></listitem>
4314 All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
4315 installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
4316 <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
4317 (You can discover where your Cygwin
4318 root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
4319 Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
4320 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4321 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4327 <para>Finally, here are some things to be aware of when using Cygwin:
4329 <listitem> <para>Cygwin doesn't deal well with filenames that include
4330 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4334 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4335 magical text in it. So other programs that don't use Cygwin's
4336 I/O libraries won't recognise such files as symlinks.
4337 In particular, programs compiled by GHC are meant to be runnable
4338 without having Cygwin, so they don't use the Cygwin library, so
4339 they don't recognise symlinks.
4343 Win32 has a <command>find</command> command which is not the same as Cygwin's find.
4344 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4345 before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4346 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4347 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4354 <Sect2><Title>Other things you need to install</Title>
4356 <para>You have to install the following other things to build GHC:
4360 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4361 This is what you will use to compile GHC. Add it in your
4362 <constant>PATH</constant>: the installer tells you the path element
4363 you need to add upon completion.
4369 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4370 Happy is a parser generator used to compile the Haskell grammar. Add it in your
4371 <constant>PATH</constant>.
4377 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4378 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">).
4379 Just pick up a mingw bundle at
4380 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4381 We install it in <filename>c:/mingw</filename>.
4383 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4384 They are only going to get used by explicit access (via the --with-gcc flag you
4385 give to <Command>configure</Command> later). If you do add them to your path
4386 you are likely to get into a mess because their names overlap with Cygwin binaries.
4392 <para>We use <command>emacs</command> a lot, so we install that too.
4393 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4394 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4395 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4396 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4397 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4398 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4404 <para> Finally, check out a copy of GHC sources from
4405 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
4412 <Sect2><Title>Building GHC</Title>
4415 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
4416 the bullets below only tell
4417 you about Windows-specific wrinkles.</para>
4421 Run <Command>autoconf</Command> both in <filename>fptools</filename>
4422 and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
4423 get an error when you run <filename>./configure</filename>:
4426 creating mk/config.h
4427 mk/config.h is unchanged
4429 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4430 ./configure: ./configure: No such file or directory
4431 configure: error: ./configure failed for ghc
4436 <listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
4437 read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
4440 /usr/bin/autoconf: cannot create configure: permission denied
4442 Solution: delete <filename>configure</filename> first.
4447 You either need to add <filename>ghc</filename> to your
4448 <constant>PATH</constant> before you invoke
4449 <Command>configure</Command>, or use the <Command>configure</Command>
4450 option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
4455 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4456 This file occasionally remembers out-of-date configuration information, which
4457 can be really confusing.
4463 After <command>autoconf</command> run <command>./configure</command> in
4464 <filename>fptools/</filename> thus:
4467 ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
4469 This is the point at which you specify that you are building GHC-mingw
4470 (see <xref linkend="ghc-mingw">). </para>
4472 <para> Both these options are important! It's possible to get into
4473 trouble using the wrong C compiler!</para>
4475 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4476 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4477 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4478 understand a Cygwin path. For example, if you
4479 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4480 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4481 time it tries to invoke it. Worse, the failure comes with
4482 no error message whatsoever. GHC simply fails silently when first invoked,
4483 typically leaving you with this:
4485 make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4486 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4487 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4488 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4489 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4490 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4491 -optc-fomit-frame-pointer -O2 -static
4492 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4493 make[2]: *** [Adjustor.o] Error 1
4494 make[1]: *** [all] Error 1
4495 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4496 make: *** [all] Error 1
4502 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
4503 you'll have to do something more like:
4505 ./configure --with-gcc=...the Cygwin gcc...
4510 <listitem><para> You almost certainly want to set
4514 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
4515 This tells the build system not to split each library into a myriad of little object files, one
4516 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4517 it dramatically increases the time taken to build the libraries in the first place.
4521 <listitem><para> Do not attempt to build the documentation.
4522 It needs all kinds of wierd Jade stuff that we haven't worked out for
4523 Win32.</para></listitem>