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>
12 <para>The Glasgow fptools suite is a collection of Functional
13 Programming related tools, including the Glasgow Haskell
14 Compiler (GHC). The source code for the whole suite is kept in
15 a single CVS repository and shares a common build and
16 installation system.</para>
18 <para>This guide is intended for people who want to build or
19 modify programs from the Glasgow <literal>fptools</literal>
20 suite (as distinct from those who merely want to
21 <emphasis>run</emphasis> them). Installation instructions are
22 now provided in the user guide.</para>
24 <para>The bulk of this guide applies to building on Unix
25 systems; see <xref linkend="winbuild"> for Windows notes.</para>
31 <sect1 id="sec-getting">
32 <title>Getting the sources</title>
34 <para>You can get your hands on the <literal>fptools</literal>
40 <term><indexterm><primary>Source
41 distributions</primary></indexterm>Source distributions</term>
43 <para>You have a supported platform, but (a) you like
44 the warm fuzzy feeling of compiling things yourself;
45 (b) you want to build something ``extra”—e.g., a
46 set of libraries with strictness-analysis turned off; or
47 (c) you want to hack on GHC yourself.</para>
49 <para>A source distribution contains complete sources for
50 one or more projects in the <literal>fptools</literal>
51 suite. Not only that, but the more awkward
52 machine-independent steps are done for you. For example, if
54 <command>happy</command><indexterm><primary>happy</primary></indexterm>
55 you'll find it convenient that the source distribution
56 contains the result of running <command>happy</command> on
57 the parser specifications. If you don't want to alter the
58 parser then this saves you having to find and install
59 <command>happy</command>. You will still need a working
60 version of GHC (version 5.x or later) on your machine in
61 order to compile (most of) the sources, however.</para>
66 <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
68 <para>We make releases infrequently. If you want more
69 up-to-the minute (but less tested) source code then you need
70 to get access to our CVS repository.</para>
72 <para>All the <literal>fptools</literal> source code is held
73 in a CVS repository. CVS is a pretty good source-code
74 control system, and best of all it works over the
77 <para>The repository holds source code only. It holds no
78 mechanically generated files at all. So if you check out a
79 source tree from CVS you will need to install every utility
80 so that you can build all the derived files from
83 <para>More information about our CVS repository can be found
84 in <xref linkend="sec-cvs">.</para>
89 <para>If you are going to do any building from sources (either
90 from a source distribution or the CVS repository) then you need to
91 read all of this manual in detail.</para>
95 <title>Using the CVS repository</title>
97 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
98 sources for various software projects. CVS lets several people
99 work on the same software at the same time, allowing changes to be
100 checked in incrementally. </para>
102 <para>This section is a set of guidelines for how to use our CVS
103 repository, and will probably evolve in time. The main thing to
104 remember is that most mistakes can be undone, but if there's
105 anything you're not sure about feel free to bug the local CVS
106 meister (namely Jeff Lewis
107 <email>jlewis@galois.com</email>). </para>
109 <sect2 id="cvs-access">
110 <title>Getting access to the CVS Repository</title>
112 <para>You can access the repository in one of two ways:
113 read-only (<xref linkend="cvs-read-only">), or read-write (<xref
114 linkend="cvs-read-write">).</para>
116 <sect3 id="cvs-read-only">
117 <title>Remote Read-only CVS Access</title>
119 <para>Read-only access is available to anyone - there's no
120 need to ask us first. With read-only CVS access you can do
121 anything except commit changes to the repository. You can
122 make changes to your local tree, and still use CVS's merge
123 facility to keep your tree up to date, and you can generate
124 patches using 'cvs diff' in order to send to us for
127 <para>To get read-only access to the repository:</para>
131 <para>Make sure that <application>cvs</application> is
132 installed on your machine.</para>
135 <para>Set your <literal>$CVSROOT</literal> environment variable to
136 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
137 <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
138 have any trailing spaces on that line, otherwise CVS will respond with
139 a perplexing message like
140 <screen>/cvs : no such repository</screen></para>
143 <para>Run the command</para>
144 <screen>$ cvs login</screen>
145 <para>The password is simply <literal>cvs</literal>. This
146 sets up a file in your home directory called
147 <literal>.cvspass</literal>, which squirrels away the
148 dummy password, so you only need to do this step once.</para>
152 <para>Now go to <xref linkend="cvs-first">.</para>
157 <sect3 id="cvs-read-write">
158 <title>Remote Read-Write CVS Access</title>
160 <para>We generally supply read-write access to folk doing
161 serious development on some part of the source tree, when
162 going through us would be a pain. If you're developing some
163 feature, or think you have the time and inclination to fix
164 bugs in our sources, feel free to ask for read-write
165 access. There is a certain amount of responsibility that goes
166 with commit privileges; we are more likely to grant you access
167 if you've demonstrated your competence by sending us patches
168 via mail in the past.</para>
170 <para>To get remote read-write CVS access, you need to do the
171 following steps.</para>
175 <para>Make sure that <literal>cvs</literal> and
176 <literal>ssh</literal> are both installed on your
181 <para>Generate a DSA private-key/public-key pair, thus:</para>
182 <screen>$ ssh-keygen -d</screen>
183 <para>(<literal>ssh-keygen</literal> comes with
184 <literal>ssh</literal>.) Running <literal>ssh-keygen
185 -d</literal> creates the private and public keys in
186 <literal>$HOME/.ssh/id_dsa</literal> and
187 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
188 (assuming you accept the standard defaults).</para>
190 <para><literal>ssh-keygen -d</literal> will only work if
191 you have Version 2 <literal>ssh</literal> installed; it
192 will fail harmlessly otherwise. If you only have Version
193 1 you can instead generate an RSA key pair using plain</para>
194 <screen>$ ssh-keygen</screen>
196 <para>Doing so creates the private and public RSA keys in
197 <literal>$HOME/.ssh/identity</literal> and
198 <literal>$HOME/.ssh/identity.pub</literal>
201 <para>[Deprecated.] Incidentally, you can force a Version
202 2 <literal>ssh</literal> to use the Version 1 protocol by
203 creating <literal>$HOME/config</literal> with the
204 following in it:</para>
205 <programlisting>BatchMode Yes
208 Protocol 1</programlisting>
210 <para>In both cases, <literal>ssh-keygen</literal> will
211 ask for a <firstterm>passphrase</firstterm>. The
212 passphrase is a password that protects your private key.
213 In response to the 'Enter passphrase' question, you can
217 <para>[Recommended.] Enter a passphrase, which you
218 will quote each time you use CVS.
219 <literal>ssh-agent</literal> makes this entirely
223 <para>[Deprecated.] Just hit return (i.e. use an empty
224 passphrase); then you won't need to quote the
225 passphrase when using CVS. The downside is that
226 anyone who can see into your <literal>.ssh</literal>
227 directory, and thereby get your private key, can mess
228 up the repository. So you must keep the
229 <literal>.ssh</literal> directory with draconian
230 no-access permissions.</para>
236 <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
243 <para>Send a message to to the CVS repository
244 administrator (currently Jeff Lewis
245 <email>jeff@galois.com</email>), containing:</para>
248 <para>Your desired user-name.</para>
251 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
252 <literal>.ssh/identity.pub</literal>).</para>
255 <para>He will set up your account.</para>
259 <para>Set the following environment variables:</para>
263 <constant>$HOME</constant>: points to your home directory. This is where CVS
264 will look for its <filename>.cvsrc</filename> file.
270 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
272 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
273 <literal>ssh</literal> assumes that your CVS client
274 understands how to execute shell script
275 ("#!"s,really), which is what
276 <literal>ssh</literal> is. This may not be the case on
277 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
278 <literal>ssh1</literal>.</para>
282 <para><literal>$CVSROOT</literal> to
283 <literal>:ext:</literal><replaceable>your-username</replaceable>
284 <literal>@cvs.haskell.org:/home/cvs/root</literal>
285 where <replaceable>your-username</replaceable> is your user name on
286 <literal>cvs.haskell.org</literal>.
288 <para>The <literal>CVSROOT</literal> environment variable will
289 be recorded in the checked-out tree, so you don't need to set
290 this every time. </para>
296 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
297 if you want to use an Emacs buffer for typing in those long commit messages.
303 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
304 set this to point to <filename>bash.exe</filename>.
315 Put the following in <filename>$HOME/.cvsrc</filename>:
318 <programlisting>checkout -P
321 diff -u</programlisting>
324 These are the default options for the specified CVS commands,
325 and represent better defaults than the usual ones. (Feel
326 free to change them.)
330 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
331 the 8.3 DOS filesystem, but that restriction should have
332 been lifted by now (i.e., you're using VFAT or later filesystems.) If
333 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
341 <para>[Experts.] Once your account is set up, you can get
342 access from other machines without bothering Jeff, thus:</para>
345 <para>Generate a public/private key pair on the new
349 <para>Use ssh to log in to
350 <literal>cvs.haskell.org</literal>, from your old
354 <para>Add the public key for the new machine to the file
355 <literal>$HOME/ssh/authorized_keys</literal> on
356 <literal>cvs.haskell.org</literal>.
357 (<literal>authorized_keys2</literal>, I think, for Version
361 <para>Make sure that the new version of
362 <literal>authorized_keys</literal> still has 600 file
371 <sect2 id="cvs-first">
372 <title>Checking Out a Source Tree</title>
376 <para>Make sure you set your <literal>CVSROOT</literal>
377 environment variable according to either of the remote
378 methods above. The Approved Way to check out a source tree
379 is as follows:</para>
381 <screen>$ cvs checkout fpconfig</screen>
383 <para>At this point you have a new directory called
384 <literal>fptools</literal> which contains the basic stuff
385 for the fptools suite, including the configuration files and
386 some other junk. </para>
388 <para>[Windows users.] The following messages appear to be harmless:
389 <screen>setsockopt IPTOS_LOWDELAY: Invalid argument
390 setsockopt IPTOS_THROUGHPUT: Invalid argument</screen>
394 <para>You can call the fptools directory whatever you like,
395 CVS won't mind: </para>
397 <screen>$ mv fptools <replaceable>directory</replaceable></screen>
399 <para> NB: after you've read the CVS manual you might be
400 tempted to try</para>
401 <screen>$ cvs checkout -d <replaceable>directory</replaceable> fpconfig</screen>
403 <para>instead of checking out <literal>fpconfig</literal>
404 and then renaming it. But this doesn't work, and will
405 result in checking out the entire repository instead of just
406 the <literal>fpconfig</literal> bit.</para>
407 <screen>$ cd <replaceable>directory</replaceable>
408 $ cvs checkout ghc hslibs libraries</screen>
410 <para>The second command here checks out the relevant
411 modules you want to work on. For a GHC build, for instance,
412 you need at least the <literal>ghc</literal>,
413 <literal>hslibs</literal> and <literal>libraries</literal>
414 modules (for a full list of the projects available, see
415 <xref linkend="projects">).</para>
417 <para>Remember that if you do not have
418 <literal>happy</literal> and/or <literal>Alex</literal>
419 installed, you need to check them out as well.</para>
424 <sect2 id="cvs-committing">
425 <title>Committing Changes</title>
427 <para>This is only if you have read-write access to the
428 repository. For anoncvs users, CVS will issue a "read-only
429 repository" error if you try to commit changes.</para>
433 <para>Build the software, if necessary. Unless you're just
434 working on documentation, you'll probably want to build the
435 software in order to test any changes you make.</para>
439 <para>Make changes. Preferably small ones first.</para>
443 <para>Test them. You can see exactly what changes you've
444 made by using the <literal>cvs diff</literal> command:</para>
445 <screen>$ cvs diff</screen>
446 <para>lists all the changes (using the
447 <literal>diff</literal> command) in and below the current
448 directory. In emacs, <literal>C-c C-v =</literal> runs
449 <literal>cvs diff</literal> on the current buffer and shows
450 you the results.</para>
454 <para>If you changed something in the
455 <literal>fptools/libraries</literal> subdirectories, also run
456 <literal>make html</literal> to check if the documentation can
457 be generated successfully, too.</para>
461 <para>Before checking in a change, you need to update your
465 $ cvs update</screen>
466 <para>This pulls in any changes that other people have made,
467 and merges them with yours. If there are any conflicts, CVS
468 will tell you, and you'll have to resolve them before you
469 can check your changes in. The documentation describes what
470 to do in the event of a conflict.</para>
472 <para>It's not always necessary to do a full cvs update
473 before checking in a change, since CVS will always tell you
474 if you try to check in a file that someone else has changed.
475 However, you should still update at regular intervals to
476 avoid making changes that don't work in conjuction with
477 changes that someone else made. Keeping an eye on what goes
478 by on the mailing list can help here.</para>
482 <para>When you're happy that your change isn't going to
483 break anything, check it in. For a one-file change:</para>
485 <screen>$ cvs commit <replaceable>filename</replaceable></screen>
487 <para>CVS will then pop up an editor for you to enter a
488 "commit message", this is just a short description
489 of what your change does, and will be kept in the history of
492 <para>If you're using emacs, simply load up the file into a
493 buffer and type <literal>C-x C-q</literal>, and emacs will
494 prompt for a commit message and then check in the file for
497 <para>For a multiple-file change, things are a bit
498 trickier. There are several ways to do this, but this is the
499 way I find easiest. First type the commit message into a
500 temporary file. Then either</para>
502 <screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable></screen>
504 <para>or, if nothing else has changed in this part of the
507 <screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable></screen>
509 <para>where <replaceable>directory</replaceable> is a common
510 parent directory for all your changes, and
511 <replaceable>commit-message</replaceable> is the name of the
512 file containing the commit message.</para>
514 <para>Shortly afterwards, you'll get some mail from the
515 relevant mailing list saying which files changed, and giving
516 the commit message. For a multiple-file change, you should
517 still get only <emphasis>one</emphasis> message.</para>
522 <sect2 id="cvs-update">
523 <title>Updating Your Source Tree</title>
525 <para>It can be tempting to cvs update just part of a source
526 tree to bring in some changes that someone else has made, or
527 before committing your own changes. This is NOT RECOMMENDED!
528 Quite often changes in one part of the tree are dependent on
529 changes in another part of the tree (the
530 <literal>mk/*.mk</literal> files are a good example where
531 problems crop up quite often). Having an inconsistent tree is a
532 major cause of headaches. </para>
534 <para>So, to avoid a lot of hassle, follow this recipe for
535 updating your tree:</para>
538 $ cvs update -P 2>&1 | tee log</screen>
540 <para>Look at the log file, and fix any conflicts (denoted by a
541 <quote>C</quote> in the first column). New directories may have
542 appeared in the repository; CVS doesn't check these out by
543 default, so to get new directories you have to explicitly do
544 <screen>$ cvs update -d</screen>
545 in each project subdirectory. Don't do this at the top level,
546 because then <emphasis>all</emphasis> the projects will be
549 <para>If you're using multiple build trees, then for every build
550 tree you have pointing at this source tree, you need to update
551 the links in case any new files have appeared: </para>
553 <screen>$ cd <replaceable>build-tree</replaceable>
554 $ lndir <replaceable>source-tree</replaceable></screen>
556 <para>Some files might have been removed, so you need to remove
557 the links pointing to these non-existent files:</para>
559 <screen>$ find . -xtype l -exec rm '{}' \;</screen>
561 <para>To be <emphasis>really</emphasis> safe, you should do
564 <screen>$ gmake all</screen>
566 <para>from the top-level, to update the dependencies and build
567 any changed files. </para>
570 <sect2 id="cvs-tags">
571 <title>GHC Tag Policy</title>
573 <para>If you want to check out a particular version of GHC,
574 you'll need to know how we tag versions in the repository. The
575 policy (as of 4.04) is:</para>
579 <para>The tree is branched before every major release. The
580 branch tag is <literal>ghc-x-xx-branch</literal>, where
581 <literal>x-xx</literal> is the version number of the release
582 with the <literal>'.'</literal> replaced by a
583 <literal>'-'</literal>. For example, the 4.04 release lives
584 on <literal>ghc-4-04-branch</literal>.</para>
588 <para>The release itself is tagged with
589 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
590 called <literal>ghc-4-06</literal>.</para>
594 <para>We didn't always follow these guidelines, so to see
595 what tags there are for previous versions, do <literal>cvs
596 log</literal> on a file that's been around for a while (like
597 <literal>fptools/ghc/README</literal>).</para>
601 <para>So, to check out a fresh GHC 4.06 tree you would
604 <screen>$ cvs co -r ghc-4-06 fpconfig
606 $ cvs co -r ghc-4-06 ghc hslibs</screen>
609 <sect2 id="cvs-hints">
610 <title>General Hints</title>
614 <para>As a general rule: commit changes in small units,
615 preferably addressing one issue or implementing a single
616 feature. Provide a descriptive log message so that the
617 repository records exactly which changes were required to
618 implement a given feature/fix a bug. I've found this
619 <emphasis>very</emphasis> useful in the past for finding out
620 when a particular bug was introduced: you can just wind back
621 the CVS tree until the bug disappears.</para>
625 <para>Keep the sources at least *buildable* at any given
626 time. No doubt bugs will creep in, but it's quite easy to
627 ensure that any change made at least leaves the tree in a
628 buildable state. We do nightly builds of GHC to keep an eye
629 on what things work/don't work each day and how we're doing
630 in relation to previous verions. This idea is truely wrecked
631 if the compiler won't build in the first place!</para>
635 <para>To check out extra bits into an already-checked-out
636 tree, use the following procedure. Suppose you have a
637 checked-out fptools tree containing just ghc, and you want
638 to add nofib to it:</para>
641 $ cvs checkout nofib</screen>
646 $ cvs update -d nofib</screen>
648 <para>(the -d flag tells update to create a new
649 directory). If you just want part of the nofib suite, you
653 $ cvs checkout nofib/spectral</screen>
655 <para>This works because <literal>nofib</literal> is a
656 module in its own right, and spectral is a subdirectory of
657 the nofib module. The path argument to checkout must always
658 start with a module name. There's no equivalent form of this
659 command using <literal>update</literal>.</para>
665 <sect1 id="projects">
666 <title>What projects are there?</title>
668 <para>The <literal>fptools</literal> suite consists of several
669 <firstterm>projects</firstterm>, most of which can be downloaded,
670 built and installed individually. Each project corresponds to a
671 subdirectory in the source tree, and if checking out from CVS then
672 each project can be checked out individually by sitting in the top
673 level of your source tree and typing <command>cvs checkout
674 <replaceable>project</replaceable></command>.</para>
676 <para>Here is a list of the projects currently available:</para>
681 <literal>alex</literal>
682 <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
686 url="http://www.haskell.org/alex/">Alex</ulink> lexical
687 analyser generator for Haskell.</para>
693 <literal>ghc</literal>
694 <indexterm><primary><literal>ghc</literal></primary>
695 <secondary>project</secondary></indexterm>
698 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
699 Haskell Compiler</ulink> (minus libraries). Absolutely
700 required for building GHC.</para>
706 <literal>glafp-utils</literal>
707 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
710 <para>Utility programs, some of which are used by the
711 build/installation system. Required for pretty much
718 <literal>greencard</literal>
719 <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
723 url="http://www.haskell.org/greencard/">GreenCard</ulink>
724 system for generating Haskell foreign function
731 <literal>haggis</literal>
732 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
736 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
737 Haskell GUI framework.</para>
743 <literal>haddock</literal>
744 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
748 url="http://www.haskell.org/haddock/">Haddock</ulink>
749 documentation tool.</para>
755 <literal>happy</literal>
756 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
760 url="http://www.haskell.org/happy/">Happy</ulink> Parser
767 <literal>hdirect</literal>
768 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
772 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
773 Haskell interoperability tool.</para>
779 <literal>hood</literal>
780 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
783 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
784 Object Observation Debugger</ulink>.</para>
790 <literal>hslibs</literal>
791 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
794 <para>Supplemental libraries for GHC
795 (<emphasis>required</emphasis> for building GHC).</para>
801 <literal>libraries</literal>
802 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
805 <para>Hierarchical Haskell library suite
806 (<emphasis>required</emphasis> for building GHC).</para>
812 <literal>mhms</literal>
813 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
816 <para>The Modular Haskell Metric System.</para>
822 <literal>nofib</literal>
823 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
826 <para>The NoFib suite: A collection of Haskell programs used
827 primarily for benchmarking.</para>
833 <literal>testsuite</literal>
834 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
837 <para>A testing framework, including GHC's regression test
843 <para>So, to build GHC you need at least the
844 <literal>ghc</literal>, <literal>libraries</literal> and
845 <literal>hslibs</literal> projects (a GHC source distribution will
846 already include the bits you need).</para>
849 <sect1 id="sec-build-checks">
850 <title>Things to check before you start</title>
852 <para>Here's a list of things to check before you get
857 <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
858 space needed: from about 100Mb for a basic GHC
859 build, up to probably 500Mb for a GHC build with everything
860 included (libraries built several different ways,
865 <para>Use an appropriate machine / operating system. <xref
866 linkend="sec-port-info"> lists the supported platforms; if
867 yours isn't amongst these then you can try porting GHC (see
868 <xref linkend="sec-porting-ghc">).</para>
872 <para>Be sure that the “pre-supposed” utilities are
873 installed. <xref linkend="sec-pre-supposed">
878 <para>If you have any problem when building or installing the
879 Glasgow tools, please check the “known pitfalls” (<xref
880 linkend="sec-build-pitfalls">). Also check the FAQ for the
881 version you're building, which is part of the User's Guide and
882 available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
885 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
887 <para>If you feel there is still some shortcoming in our
888 procedure or instructions, please report it.</para>
890 <para>For GHC, please see the <ulink
891 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
892 section of the GHC Users' Guide</ulink>, to maximise the
893 usefulness of your report.</para>
895 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
896 <para>If in doubt, please send a message to
897 <email>glasgow-haskell-bugs@haskell.org</email>.
898 <indexterm><primary>bugs</primary><secondary>mailing
899 list</secondary></indexterm></para>
904 <sect1 id="sec-port-info">
905 <title>What machines the Glasgow tools run on</title>
907 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
908 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
909 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
911 <para>The main question is whether or not the Haskell compiler
912 (GHC) runs on your platform.</para>
914 <para>A “platform” is a
915 architecture/manufacturer/operating-system combination, such as
916 <literal>sparc-sun-solaris2</literal>. Other common ones are
917 <literal>alpha-dec-osf2</literal>,
918 <literal>hppa1.1-hp-hpux9</literal>,
919 <literal>i386-unknown-linux</literal>,
920 <literal>i386-unknown-solaris2</literal>,
921 <literal>i386-unknown-freebsd</literal>,
922 <literal>i386-unknown-cygwin32</literal>,
923 <literal>m68k-sun-sunos4</literal>,
924 <literal>mips-sgi-irix5</literal>,
925 <literal>sparc-sun-sunos4</literal>,
926 <literal>sparc-sun-solaris2</literal>,
927 <literal>powerpc-ibm-aix</literal>.</para>
929 <para>Some libraries may only work on a limited number of
930 platforms; for example, a sockets library is of no use unless the
931 operating system supports the underlying BSDisms.</para>
934 <title>What platforms the Haskell compiler (GHC) runs on</title>
936 <indexterm><primary>fully-supported platforms</primary></indexterm>
937 <indexterm><primary>native-code generator</primary></indexterm>
938 <indexterm><primary>registerised ports</primary></indexterm>
939 <indexterm><primary>unregisterised ports</primary></indexterm>
941 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
942 native-code generator; (b) next best is a
943 “registerised” port; (c) the bare minimum is an
944 “unregisterised” port.
945 (“Unregisterised” is so terrible that we won't say
946 more about it).</para>
948 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
949 FreeBSD and Linux, so those are the best supported platforms,
950 unsurprisingly.</para>
952 <para>Here's everything that's known about GHC ports. We
953 identify platforms by their “canonical”
954 CPU/Manufacturer/OS triple.</para>
958 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
959 <indexterm><primary>alpha-dec-osf</primary></indexterm>
960 <indexterm><primary>alpha-dec-linux</primary></indexterm>
961 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
962 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
963 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
966 <para>The OSF port is currently working (as of GHC version
967 5.02.1) and well supported. The native code generator is
968 currently non-working. Other operating systems will
969 require some minor porting.</para>
974 <term>sparc-sun-sunos4
975 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
978 <para>Probably works with minor tweaks, hasn't been tested
984 <term>sparc-sun-solaris2
985 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
988 <para>Fully supported (at least for Solaris 2.7 and 2.6),
989 including native-code generator.</para>
994 <term>sparc-unknown-openbsd
995 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
998 <para>Supported, including native-code generator. The
999 same should also be true of NetBSD</para>
1004 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
1005 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1008 <para>A registerised port is available for version 4.08,
1009 but GHC hasn't been built on that platform since (as far
1010 as we know). No native-code generator.</para>
1015 <term>i386-unknown-linux (PCs running Linux, ELF binary format)
1016 <indexterm><primary>i386-*-linux</primary></indexterm>
1019 <para>GHC works registerised and has a native code
1020 generator. You <emphasis>must</emphasis> have GCC 2.7.x
1021 or later. NOTE about <literal>glibc</literal> versions:
1022 GHC binaries built on a system running <literal>glibc
1023 2.0</literal> won't work on a system running
1024 <literal>glibc 2.1</literal>, and vice versa. In general,
1025 don't expect compatibility between
1026 <literal>glibc</literal> versions, even if the shared
1027 library version hasn't changed.</para>
1032 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
1033 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1036 <para>GHC works registerised. Pre-built packages are
1037 available in the native package format, so if you just
1038 need binaries you're better off just installing the
1039 package (it might even be on your installation
1045 <term>i386-unknown-openbsd (PCs running OpenBSD)
1046 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1049 <para>Supported, with native code generator. Packages are
1050 available through the ports system in the native package
1056 <term>i386-unknown-netbsd (PCs running NetBSD)
1057 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1060 <para>Will require some minor porting effort, but should
1061 work registerised.</para>
1066 <term>i386-unknown-mingw32 (PCs running Windows)
1067 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1070 <para>Fully supported under Win9x, WinNT, Win2k, and
1071 WinXP. Includes a native code generator. Building from
1072 source requires a recent <ulink
1073 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1074 to be installed.</para>
1079 <term>ia64-unknown-linux
1080 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1083 <para>Supported, except there is no native code
1089 <term>x86_64-unknown-linux
1090 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1093 <para>GHC currently works unregisterised. A registerised
1094 port is in progress.</para>
1099 <term>amd64-unknown-openbsd
1100 <indexterm><primary>amd64-unknown-linux</primary></indexterm>
1103 <para>(This is the same as x86_64-unknown-openbsd). GHC
1104 currently works unregisterised. A registerised port is in
1110 <term>mips-sgi-irix5
1111 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1114 <para>Port has worked in the past, but hasn't been tested
1115 for some time (and will certainly have rotted in various
1116 ways). As usual, we don't have access to machines and
1117 there hasn't been an overwhelming demand for this port,
1118 but feel free to get in touch.</para>
1123 <term>mips64-sgi-irix6
1124 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
1127 <para>GHC currently works unregisterised.</para>
1132 <term>powerpc-ibm-aix
1133 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1136 <para>Port currently doesn't work, needs some minimal
1137 porting effort. As usual, we don't have access to
1138 machines and there hasn't been an overwhelming demand for
1139 this port, but feel free to get in touch.</para>
1144 <term>powerpc-apple-darwin
1145 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1148 <para>Supported registerised. Native code generator is
1149 almost working.</para>
1154 <term>powerpc-apple-linux
1155 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1158 <para>Not supported (yet).</para>
1163 <para>Various other systems have had GHC ported to them in the
1164 distant past, including various Motorola 68k boxes. The 68k
1165 support still remains, but porting to one of these systems will
1166 certainly be a non-trivial task.</para>
1170 <title>What machines the other tools run on</title>
1172 <para>Unless you hear otherwise, the other tools work if GHC
1178 <sect1 id="sec-pre-supposed">
1179 <title>Installing pre-supposed utilities</title>
1181 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1182 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1184 <para>Here are the gory details about some utility programs you
1185 may need; <command>perl</command>, <command>gcc</command> and
1186 <command>happy</command> are the only important
1187 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1188 important if you're going for Parallel Haskell.) The
1189 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1190 script will tell you if you are missing something.</para>
1196 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1197 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1200 <para>GHC is required to build many of the tools, including
1201 GHC itself. If you need to port GHC to your platform
1202 because there isn't a binary distribution of GHC available,
1203 then see <xref linkend="sec-porting-ghc">.</para>
1205 <para>Which version of GHC you need will depend on the
1206 packages you intend to build. GHC itself will normally
1207 build using one of several older versions of itself - check
1208 the announcement or release notes for details.</para>
1214 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1215 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1218 <para><emphasis>You have to have Perl to proceed!</emphasis>
1219 Perl version 5 at least is required. GHC has been known to
1220 tickle bugs in Perl, so if you find that Perl crashes when
1221 running GHC try updating (or downgrading) your Perl
1222 installation. Versions of Perl that we use and are known to
1223 be fairly stable are 5.005 and 5.6.1.</para>
1225 <para>For Win32 platforms, you should use the binary
1226 supplied in the InstallShield (copy it to
1227 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1230 <para>Perl should be put somewhere so that it can be invoked
1231 by the <literal>#!</literal> script-invoking
1232 mechanism. The full pathname may need to be less than 32
1233 characters long on some systems.</para>
1238 <term>GNU C (<command>gcc</command>)
1239 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
1240 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
1243 <para>We recommend using GCC version 2.95.2 on all
1244 platforms. Failing that, version 2.7.2 is stable on most
1245 platforms. Earlier versions of GCC can be assumed not to
1246 work, and versions in between 2.7.2 and 2.95.2 (including
1247 <command>egcs</command>) have varying degrees of stability
1248 depending on the platform.</para>
1250 <para>GCC 3.2 is currently known to have problems building
1251 GHC on Sparc, but is stable on x86.</para>
1253 <para>If your GCC dies with “internal error” on
1254 some GHC source file, please let us know, so we can report
1255 it and get things improved. (Exception: on x86
1256 boxes—you may need to fiddle with GHC's
1257 <option>-monly-N-regs</option> option; see the User's
1264 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
1267 <para>The fptools build system makes heavy use of features
1268 specific to GNU <command>make</command>, so you must have
1269 this installed in order to build any of the fptools
1276 <indexterm><primary>Happy</primary></indexterm>
1279 <para>Happy is a parser generator tool for Haskell, and is
1280 used to generate GHC's parsers. Happy is written in
1281 Haskell, and is a project in the CVS repository
1282 (<literal>fptools/happy</literal>). It can be built from
1283 source, but bear in mind that you'll need GHC installed in
1284 order to build it. To avoid the chicken/egg problem,
1285 install a binary distribution of either Happy or GHC to get
1286 started. Happy distributions are available from <ulink
1287 url="http://www.haskell.org/happy/">Happy's Web
1288 Page</ulink>.</para>
1294 <indexterm><primary>Alex</primary></indexterm>
1297 <para>Alex is a lexical-analyser generator for Haskell,
1298 which GHC uses to generate its lexer. Like Happy, Alex is
1299 written in Haskell and is a project in the CVS repository.
1300 Alex distributions are available from <ulink
1301 url="http://www.haskell.org/alex/">Alex's Web
1302 Page</ulink>.</para>
1308 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
1309 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
1312 <para>GNU autoconf is needed if you intend to build from the
1313 CVS sources, it is <emphasis>not</emphasis> needed if you
1314 just intend to build a standard source distribution.</para>
1316 <para>Version 2.52 or later of the autoconf package is required.
1317 NB. version 2.13 will no longer work, as of GHC version
1320 <para><command>autoreconf</command> (from the autoconf package)
1321 recursively builds <command>configure</command> scripts from
1322 the corresponding <filename>configure.ac</filename> and
1323 <filename>aclocal.m4</filename> files. If you modify one of
1324 the latter files, you'll need <command>autoreconf</command> to
1325 rebuild the corresponding <filename>configure</filename>.</para>
1330 <term><command>sed</command>
1331 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1332 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1335 <para>You need a working <command>sed</command> if you are
1336 going to build from sources. The build-configuration stuff
1337 needs it. GNU sed version 2.0.4 is no good! It has a bug
1338 in it that is tickled by the build-configuration. 2.0.5 is
1339 OK. Others are probably OK too (assuming we don't create too
1340 elaborate configure scripts.)</para>
1345 <para>One <literal>fptools</literal> project is worth a quick note
1346 at this point, because it is useful for all the others:
1347 <literal>glafp-utils</literal> contains several utilities which
1348 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1349 Like <command>lndir</command> for creating symbolic link
1352 <sect2 id="pre-supposed-gph-tools">
1353 <title>Tools for building parallel GHC (GPH)</title>
1357 <term>PVM version 3:
1358 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1359 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1362 <para>PVM is the Parallel Virtual Machine on which
1363 Parallel Haskell programs run. (You only need this if you
1364 plan to run Parallel Haskell. Concurrent Haskell, which
1365 runs concurrent threads on a uniprocessor doesn't need
1366 it.) Underneath PVM, you can have (for example) a network
1367 of workstations (slow) or a multiprocessor box
1370 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1371 It is readily available on the net; I think I got it from
1372 <literal>research.att.com</literal>, in
1373 <filename>netlib</filename>.</para>
1375 <para>A PVM installation is slightly quirky, but easy to
1376 do. Just follow the <filename>Readme</filename>
1377 instructions.</para>
1382 <term><command>bash</command>:
1383 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1386 <para>Sadly, the <command>gr2ps</command> script, used to
1387 convert “parallelism profiles” to PostScript,
1388 is written in Bash (GNU's Bourne Again shell). This bug
1389 will be fixed (someday).</para>
1395 <sect2 id="pre-supposed-other-tools">
1396 <title>Other useful tools</title>
1401 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1402 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1405 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1406 to build a couple of utilities in
1407 <literal>glafp-utils</literal>. Depending on your
1408 operating system, the supplied <command>lex</command> may
1409 or may not work; you should get the GNU version.</para>
1414 <para>More tools are required if you want to format the documentation
1415 that comes with GHC and other fptools projects. See <xref
1416 linkend="building-docs">.</para>
1420 <sect1 id="sec-building-from-source">
1421 <title>Building from source</title>
1423 <indexterm><primary>Building from source</primary></indexterm>
1424 <indexterm><primary>Source, building from</primary></indexterm>
1426 <para>You've been rash enough to want to build some of the Glasgow
1427 Functional Programming tools (GHC, Happy, nofib, etc.) from
1428 source. You've slurped the source, from the CVS repository or
1429 from a source distribution, and now you're sitting looking at a
1430 huge mound of bits, wondering what to do next.</para>
1432 <para>Gingerly, you type <command>make</command>. Wrong
1435 <para>This rest of this guide is intended for duffers like me, who
1436 aren't really interested in Makefiles and systems configurations,
1437 but who need a mental model of the interlocking pieces so that
1438 they can make them work, extend them consistently when adding new
1439 software, and lay hands on them gently when they don't
1442 <sect2 id="quick-start">
1443 <title>Quick Start</title>
1445 <para>If you are starting from a source distribution, and just
1446 want a completely standard build, then the following should
1449 <screen>$ autoreconf
1452 $ make install</screen>
1454 <para>For GHC, this will do a 2-stage bootstrap build of the
1455 compiler, with profiling libraries, and install the
1458 <para>If you want to do anything at all non-standard, or you
1459 want to do some development, read on...</para>
1462 <sect2 id="sec-source-tree">
1463 <title>Your source tree</title>
1465 <para>The source code is held in your <emphasis>source
1466 tree</emphasis>. The root directory of your source tree
1467 <emphasis>must</emphasis> contain the following directories and
1472 <para><filename>Makefile</filename>: the root
1477 <para><filename>mk/</filename>: the directory that contains
1478 the main Makefile code, shared by all the
1479 <literal>fptools</literal> software.</para>
1483 <para><filename>configure.ac</filename>,
1484 <filename>config.sub</filename>,
1485 <filename>config.guess</filename>: these files support the
1486 configuration process.</para>
1490 <para><filename>install-sh</filename>.</para>
1494 <para>All the other directories are individual
1495 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1496 system—for example, the Glasgow Haskell Compiler
1497 (<literal>ghc</literal>), the Happy parser generator
1498 (<literal>happy</literal>), the <literal>nofib</literal>
1499 benchmark suite, and so on. You can have zero or more of these.
1500 Needless to say, some of them are needed to build others.</para>
1502 <para>The important thing to remember is that even if you want
1503 only one project (<literal>happy</literal>, say), you must have
1504 a source tree whose root directory contains
1505 <filename>Makefile</filename>, <filename>mk/</filename>,
1506 <filename>configure.ac</filename>, and the project(s) you want
1507 (<filename>happy/</filename> in this case). You cannot get by
1508 with just the <filename>happy/</filename> directory.</para>
1512 <title>Build trees</title>
1513 <indexterm><primary>build trees</primary></indexterm>
1514 <indexterm><primary>link trees, for building</primary></indexterm>
1516 <para>If you just want to build the software once on a single
1517 platform, then your source tree can also be your build tree, and
1518 you can skip the rest of this section.</para>
1520 <para>We often want to build multiple versions of our software
1521 for different architectures, or with different options
1522 (e.g. profiling). It's very desirable to share a single copy of
1523 the source code among all these builds.</para>
1525 <para>So for every source tree we have zero or more
1526 <emphasis>build trees</emphasis>. Each build tree is initially
1527 an exact copy of the source tree, except that each file is a
1528 symbolic link to the source file, rather than being a copy of
1529 the source file. There are “standard” Unix
1530 utilities that make such copies, so standard that they go by
1532 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1533 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1534 are two (If you don't have either, the source distribution
1535 includes sources for the X11
1536 <command>lndir</command>—check out
1537 <filename>fptools/glafp-utils/lndir</filename>). See <xref
1538 linkend="sec-storysofar"> for a typical invocation.</para>
1540 <para>The build tree does not need to be anywhere near the
1541 source tree in the file system. Indeed, one advantage of
1542 separating the build tree from the source is that the build tree
1543 can be placed in a non-backed-up partition, saving your systems
1544 support people from backing up untold megabytes of
1545 easily-regenerated, and rapidly-changing, gubbins. The golden
1546 rule is that (with a single exception—<xref
1547 linkend="sec-build-config">) <emphasis>absolutely everything in
1548 the build tree is either a symbolic link to the source tree, or
1549 else is mechanically generated</emphasis>. It should be
1550 perfectly OK for your build tree to vanish overnight; an hour or
1551 two compiling and you're on the road again.</para>
1553 <para>You need to be a bit careful, though, that any new files
1554 you create (if you do any development work) are in the source
1555 tree, not a build tree!</para>
1557 <para>Remember, that the source files in the build tree are
1558 <emphasis>symbolic links</emphasis> to the files in the source
1559 tree. (The build tree soon accumulates lots of built files like
1560 <filename>Foo.o</filename>, as well.) You can
1561 <emphasis>delete</emphasis> a source file from the build tree
1562 without affecting the source tree (though it's an odd thing to
1563 do). On the other hand, if you <emphasis>edit</emphasis> a
1564 source file from the build tree, you'll edit the source-tree
1565 file directly. (You can set up Emacs so that if you edit a
1566 source file from the build tree, Emacs will silently create an
1567 edited copy of the source file in the build tree, leaving the
1568 source file unchanged; but the danger is that you think you've
1569 edited the source file whereas actually all you've done is edit
1570 the build-tree copy. More commonly you do want to edit the
1571 source file.)</para>
1573 <para>Like the source tree, the top level of your build tree
1574 must be (a linked copy of) the root directory of the
1575 <literal>fptools</literal> suite. Inside Makefiles, the root of
1576 your build tree is called
1577 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1578 In the rest of this document path names are relative to
1579 <constant>$(FPTOOLS_TOP)</constant> unless
1580 otherwise stated. For example, the file
1581 <filename>ghc/mk/target.mk</filename> is actually
1582 <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
1585 <sect2 id="sec-build-config">
1586 <title>Getting the build you want</title>
1588 <para>When you build <literal>fptools</literal> you will be
1589 compiling code on a particular <emphasis>host
1590 platform</emphasis>, to run on a particular <emphasis>target
1591 platform</emphasis> (usually the same as the host
1592 platform)<indexterm><primary>platform</primary></indexterm>.
1593 The difficulty is that there are minor differences between
1594 different platforms; minor, but enough that the code needs to be
1595 a bit different for each. There are some big differences too:
1596 for a different architecture we need to build GHC with a
1597 different native-code generator.</para>
1599 <para>There are also knobs you can turn to control how the
1600 <literal>fptools</literal> software is built. For example, you
1601 might want to build GHC optimised (so that it runs fast) or
1602 unoptimised (so that you can compile it fast after you've
1603 modified it. Or, you might want to compile it with debugging on
1604 (so that extra consistency-checking code gets included) or off.
1607 <para>All of this stuff is called the
1608 <emphasis>configuration</emphasis> of your build. You set the
1609 configuration using a three-step process.</para>
1613 <term>Step 1: get ready for configuration.</term>
1615 <para>NOTE: if you're starting from a source distribution,
1616 rather than CVS sources, you can skip this step.</para>
1618 <para>Change directory to
1619 <constant>$(FPTOOLS_TOP)</constant> and
1620 issue the command</para>
1621 <programlisting>autoreconf</programlisting>
1622 <indexterm><primary>autoreconf</primary></indexterm>
1623 <para>(with no arguments). This GNU program (recursively) converts
1624 <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
1625 <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
1626 to a shell script called
1627 <filename>$(FPTOOLS_TOP)/configure</filename>.
1628 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
1629 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
1630 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
1631 a message like "No rule to make target 'mk/config.h.in'".
1634 <para>Some projects, including GHC, have their own configure script.
1635 <command>autoreconf</command> takes care of that, too, so all you have
1636 to do is calling <command>autoreconf</command> in the top-level directory
1637 <filename>$(FPTOOLS_TOP)</filename>.</para>
1639 <para>These steps are completely platform-independent; they just mean
1640 that the human-written files (<filename>configure.ac</filename> and
1641 <filename>aclocal.m4</filename>) can be short, although the resulting
1642 files (the <command>configure</command> shell scripts and the C header
1643 template <filename>mk/config.h.in</filename>) are long.</para>
1648 <term>Step 2: system configuration.</term>
1650 <para>Runs the newly-created <command>configure</command>
1651 script, thus:</para>
1653 <programlisting>./configure <optional><parameter>args</parameter></optional></programlisting>
1655 <para><command>configure</command>'s mission is to scurry
1656 round your computer working out what architecture it has,
1657 what operating system, whether it has the
1658 <function>vfork</function> system call, where
1659 <command>tar</command> is kept, whether
1660 <command>gcc</command> is available, where various obscure
1661 <literal>#include</literal> files are, whether it's a
1662 leap year, and what the systems manager had for lunch. It
1663 communicates these snippets of information in two
1670 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1672 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1673 substituting for things between
1674 “<literal>@</literal>” brackets. So,
1675 “<literal>@HaveGcc@</literal>” will be
1676 replaced by “<literal>YES</literal>” or
1677 “<literal>NO</literal>” depending on what
1678 <command>configure</command> finds.
1679 <filename>mk/config.mk</filename> is included by every
1680 Makefile (directly or indirectly), so the
1681 configuration information is thereby communicated to
1682 all Makefiles.</para>
1686 <para> It translates
1687 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1689 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1690 The latter is <literal>#include</literal>d by
1691 various C programs, which can thereby make use of
1692 configuration information.</para>
1696 <para><command>configure</command> takes some optional
1697 arguments. Use <literal>./configure --help</literal> to
1698 get a list of the available arguments. Here are some of
1699 the ones you might need:</para>
1703 <term><literal>--with-ghc=<parameter>path</parameter></literal>
1704 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
1707 <para>Specifies the path to an installed GHC which
1708 you would like to use. This compiler will be used
1709 for compiling GHC-specific code (eg. GHC itself).
1710 This option <emphasis>cannot</emphasis> be specified
1711 using <filename>build.mk</filename> (see later),
1712 because <command>configure</command> needs to
1713 auto-detect the version of GHC you're using. The
1714 default is to look for a compiler named
1715 <literal>ghc</literal> in your path.</para>
1720 <term><literal>--with-hc=<parameter>path</parameter></literal>
1721 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
1724 <para>Specifies the path to any installed Haskell
1725 compiler. This compiler will be used for compiling
1726 generic Haskell code. The default is to use
1727 <literal>ghc</literal>.</para>
1732 <term><literal>--with-gcc=<parameter>path</parameter></literal>
1733 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
1736 <para>Specifies the path to the installed GCC. This
1737 compiler will be used to compile all C files,
1738 <emphasis>except</emphasis> any generated by the
1739 installed Haskell compiler, which will have its own
1740 idea of which C compiler (if any) to use. The
1741 default is to use <literal>gcc</literal>.</para>
1749 <term>Step 3: build configuration.</term>
1751 <para>Next, you say how this build of
1752 <literal>fptools</literal> is to differ from the standard
1753 defaults by creating a new file
1754 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1755 <emphasis>in the build tree</emphasis>. This file is the
1756 one and only file you edit in the build tree, precisely
1757 because it says how this build differs from the source.
1758 (Just in case your build tree does die, you might want to
1759 keep a private directory of <filename>build.mk</filename>
1760 files, and use a symbolic link in each build tree to point
1761 to the appropriate one.) So
1762 <filename>mk/build.mk</filename> never exists in the
1763 source tree—you create one in each build tree from
1764 the template. We'll discuss what to put in it
1770 <para>And that's it for configuration. Simple, eh?</para>
1772 <para>What do you put in your build-specific configuration file
1773 <filename>mk/build.mk</filename>? <emphasis>For almost all
1774 purposes all you will do is put make variable definitions that
1775 override those in</emphasis>
1776 <filename>mk/config.mk.in</filename>. The whole point of
1777 <filename>mk/config.mk.in</filename>—and its derived
1778 counterpart <filename>mk/config.mk</filename>—is to define
1779 the build configuration. It is heavily commented, as you will
1780 see if you look at it. So generally, what you do is look at
1781 <filename>mk/config.mk.in</filename>, and add definitions in
1782 <filename>mk/build.mk</filename> that override any of the
1783 <filename>config.mk</filename> definitions that you want to
1784 change. (The override occurs because the main boilerplate file,
1785 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1786 includes <filename>build.mk</filename> after
1787 <filename>config.mk</filename>.)</para>
1789 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1790 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1792 <para>For example, <filename>config.mk.in</filename> contains
1793 the definition:</para>
1795 <programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
1797 <para>The accompanying comment explains that this is the list of
1798 flags passed to GHC when building GHC itself. For doing
1799 development, it is wise to add <literal>-DDEBUG</literal>, to
1800 enable debugging code. So you would add the following to
1801 <filename>build.mk</filename>:</para>
1803 <para>or, if you prefer,</para>
1805 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
1807 <para>GNU <command>make</command> allows existing definitions to
1808 have new text appended using the “<literal>+=</literal>”
1809 operator, which is quite a convenient feature.)</para>
1811 <para>If you want to remove the <literal>-O</literal> as well (a
1812 good idea when developing, because the turn-around cycle gets a
1813 lot quicker), you can just override
1814 <literal>GhcLibHcOpts</literal> altogether:</para>
1816 <programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
1818 <para>When reading <filename>config.mk.in</filename>, remember
1819 that anything between “@...@” signs is going to be substituted
1820 by <command>configure</command> later. You
1821 <emphasis>can</emphasis> override the resulting definition if
1822 you want, but you need to be a bit surer what you are doing.
1823 For example, there's a line that says:</para>
1825 <programlisting>TAR = @TarCmd@</programlisting>
1827 <para>This defines the Make variables <constant>TAR</constant>
1828 to the pathname for a <command>tar</command> that
1829 <command>configure</command> finds somewhere. If you have your
1830 own pet <command>tar</command> you want to use instead, that's
1831 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1833 <programlisting>TAR = mytar</programlisting>
1835 <para>You do not <emphasis>have</emphasis> to have a
1836 <filename>mk/build.mk</filename> file at all; if you don't,
1837 you'll get all the default settings from
1838 <filename>mk/config.mk.in</filename>.</para>
1840 <para>You can also use <filename>build.mk</filename> to override
1841 anything that <command>configure</command> got wrong. One place
1842 where this happens often is with the definition of
1843 <constant>FPTOOLS_TOP_ABS</constant>: this
1844 variable is supposed to be the canonical path to the top of your
1845 source tree, but if your system uses an automounter then the
1846 correct directory is hard to find automatically. If you find
1847 that <command>configure</command> has got it wrong, just put the
1848 correct definition in <filename>build.mk</filename>.</para>
1852 <sect2 id="sec-storysofar">
1853 <title>The story so far</title>
1855 <para>Let's summarise the steps you need to carry to get
1856 yourself a fully-configured build tree from scratch.</para>
1860 <para> Get your source tree from somewhere (CVS repository
1861 or source distribution). Say you call the root directory
1862 <filename>myfptools</filename> (it does not have to be
1863 called <filename>fptools</filename>). Make sure that you
1864 have the essential files (see <xref
1865 linkend="sec-source-tree">).</para>
1870 <para>(Optional) Use <command>lndir</command> or
1871 <command>mkshadowdir</command> to create a build tree.</para>
1873 <programlisting>$ cd myfptools
1874 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</programlisting>
1876 <para>(N.B. <command>mkshadowdir</command>'s first argument
1877 is taken relative to its second.) You probably want to give
1878 the build tree a name that suggests its main defining
1879 characteristic (in your mind at least), in case you later
1884 <para>Change directory to the build tree. Everything is
1885 going to happen there now.</para>
1887 <programlisting>$ cd /scratch/joe-bloggs/myfptools-sun4</programlisting>
1892 <para>Prepare for system configuration:</para>
1894 <programlisting>$ autoreconf</programlisting>
1896 <para>(You can skip this step if you are starting from a
1897 source distribution, and you already have
1898 <filename>configure</filename> and
1899 <filename>mk/config.h.in</filename>.)</para>
1903 <para>Do system configuration:</para>
1905 <programlisting>$ ./configure</programlisting>
1907 <para>Don't forget to check whether you need to add any
1908 arguments to <literal>configure</literal>; for example, a
1909 common requirement is to specify which GHC to use with
1910 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1914 <para>Create the file <filename>mk/build.mk</filename>,
1915 adding definitions for your desired configuration
1918 <programlisting>$ emacs mk/build.mk</programlisting>
1922 <para>You can make subsequent changes to
1923 <filename>mk/build.mk</filename> as often as you like. You do
1924 not have to run any further configuration programs to make these
1925 changes take effect. In theory you should, however, say
1926 <command>gmake clean</command>, <command>gmake all</command>,
1927 because configuration option changes could affect
1928 anything—but in practice you are likely to know what's
1933 <title>Making things</title>
1935 <para>At this point you have made yourself a fully-configured
1936 build tree, so you are ready to start building real
1939 <para>The first thing you need to know is that <emphasis>you
1940 must use GNU <command>make</command>, usually called
1941 <command>gmake</command>, not standard Unix
1942 <command>make</command></emphasis>. If you use standard Unix
1943 <command>make</command> you will get all sorts of error messages
1944 (but no damage) because the <literal>fptools</literal>
1945 <command>Makefiles</command> use GNU <command>make</command>'s
1946 facilities extensively.</para>
1948 <para>To just build the whole thing, <command>cd</command> to
1949 the top of your <literal>fptools</literal> tree and type
1950 <command>gmake</command>. This will prepare the tree and build
1951 the various projects in the correct order.</para>
1954 <sect2 id="sec-bootstrapping">
1955 <title>Bootstrapping GHC</title>
1957 <para>GHC requires a 2-stage bootstrap in order to provide
1958 full functionality, including GHCi. By a 2-stage bootstrap, we
1959 mean that the compiler is built once using the installed GHC,
1960 and then again using the compiler built in the first stage. You
1961 can also build a stage 3 compiler, but this normally isn't
1962 necessary except to verify that the stage 2 compiler is working
1965 <para>Note that when doing a bootstrap, the stage 1 compiler
1966 must be built, followed by the runtime system and libraries, and
1967 then the stage 2 compiler. The correct ordering is implemented
1968 by the top-level fptools <filename>Makefile</filename>, so if
1969 you want everything to work automatically it's best to start
1970 <command>make</command> from the top of the tree. When building
1971 GHC, the top-level fptools <filename>Makefile</filename> is set
1972 up to do a 2-stage bootstrap by default (when you say
1973 <command>make</command>). Some other targets it supports
1980 <para>Build everything as normal, including the stage 1
1988 <para>Build the stage 2 compiler only.</para>
1995 <para>Build the stage 3 compiler only.</para>
2000 <term>bootstrap</term> <term>bootstrap2</term>
2002 <para>Build stage 1 followed by stage 2.</para>
2007 <term>bootstrap3</term>
2009 <para>Build stages 1, 2 and 3.</para>
2014 <term>install</term>
2016 <para>Install everything, including the compiler built in
2017 stage 2. To override the stage, say <literal>make install
2018 stage=<replaceable>n</replaceable></literal> where
2019 <replaceable>n</replaceable> is the stage to install.</para>
2024 <para>The top-level <filename>Makefile</filename> also arranges
2025 to do the appropriate <literal>make boot</literal> steps (see
2026 below) before actually building anything.</para>
2028 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2029 and <literal>stage3</literal> targets also work in the
2030 <literal>ghc/compiler</literal> directory, but don't forget that
2031 each stage requires its own <literal>make boot</literal> step:
2032 for example, you must do</para>
2034 <screen>$ make boot stage=2</screen>
2036 <para>before <literal>make stage2</literal> in
2037 <literal>ghc/compiler</literal>.</para>
2040 <sect2 id="sec-standard-targets">
2041 <title>Standard Targets</title>
2042 <indexterm><primary>targets, standard makefile</primary></indexterm>
2043 <indexterm><primary>makefile targets</primary></indexterm>
2045 <para>In any directory you should be able to make the following:</para>
2049 <term><literal>boot</literal></term>
2051 <para>does the one-off preparation required to get ready
2052 for the real work. Notably, it does <command>gmake
2053 depend</command> in all directories that contain programs.
2054 It also builds the necessary tools for compilation to
2057 <para>Invoking the <literal>boot</literal> target
2058 explicitly is not normally necessary. From the top-level
2059 <literal>fptools</literal> directory, invoking
2060 <literal>gmake</literal> causes <literal>gmake boot
2061 all</literal> to be invoked in each of the project
2062 subdirectories, in the order specified by
2063 <literal>$(AllTargets)</literal> in
2064 <literal>config.mk</literal>.</para>
2066 <para>If you're working in a subdirectory somewhere and
2067 need to update the dependencies, <literal>gmake
2068 boot</literal> is a good way to do it.</para>
2073 <term><literal>all</literal></term>
2075 <para>makes all the final target(s) for this Makefile.
2076 Depending on which directory you are in a “final
2077 target” may be an executable program, a library
2078 archive, a shell script, or a Postscript file. Typing
2079 <command>gmake</command> alone is generally the same as
2080 typing <command>gmake all</command>.</para>
2085 <term><literal>install</literal></term>
2087 <para>installs the things built by <literal>all</literal>
2088 (except for the documentation). Where does it install
2089 them? That is specified by
2090 <filename>mk/config.mk.in</filename>; you can override it
2091 in <filename>mk/build.mk</filename>, or by running
2092 <command>configure</command> with command-line arguments
2093 like <literal>--bindir=/home/simonpj/bin</literal>; see
2094 <literal>./configure --help</literal> for the full
2100 <term><literal>install-docs</literal></term>
2102 <para>installs the documentation. Otherwise behaves just
2103 like <literal>install</literal>.</para>
2108 <term><literal>uninstall</literal></term>
2110 <para>reverses the effect of
2111 <literal>install</literal>.</para>
2116 <term><literal>clean</literal></term>
2118 <para>Delete all files from the current directory that are
2119 normally created by building the program. Don't delete
2120 the files that record the configuration, or files
2121 generated by <command>gmake boot</command>. Also preserve
2122 files that could be made by building, but normally aren't
2123 because the distribution comes with them.</para>
2128 <term><literal>distclean</literal></term>
2130 <para>Delete all files from the current directory that are
2131 created by configuring or building the program. If you
2132 have unpacked the source and built the program without
2133 creating any other files, <literal>make
2134 distclean</literal> should leave only the files that were
2135 in the distribution.</para>
2140 <term><literal>mostlyclean</literal></term>
2142 <para>Like <literal>clean</literal>, but may refrain from
2143 deleting a few files that people normally don't want to
2149 <term><literal>maintainer-clean</literal></term>
2151 <para>Delete everything from the current directory that
2152 can be reconstructed with this Makefile. This typically
2153 includes everything deleted by
2154 <literal>distclean</literal>, plus more: C source files
2155 produced by Bison, tags tables, Info files, and so
2158 <para>One exception, however: <literal>make
2159 maintainer-clean</literal> should not delete
2160 <filename>configure</filename> even if
2161 <filename>configure</filename> can be remade using a rule
2162 in the <filename>Makefile</filename>. More generally,
2163 <literal>make maintainer-clean</literal> should not delete
2164 anything that needs to exist in order to run
2165 <filename>configure</filename> and then begin to build the
2171 <term><literal>check</literal></term>
2173 <para>run the test suite.</para>
2178 <para>All of these standard targets automatically recurse into
2179 sub-directories. Certain other standard targets do not:</para>
2183 <term><literal>configure</literal></term>
2185 <para>is only available in the root directory
2186 <constant>$(FPTOOLS_TOP)</constant>; it has
2187 been discussed in <xref
2188 linkend="sec-build-config">.</para>
2193 <term><literal>depend</literal></term>
2195 <para>make a <filename>.depend</filename> file in each
2196 directory that needs it. This <filename>.depend</filename>
2197 file contains mechanically-generated dependency
2198 information; for example, suppose a directory contains a
2199 Haskell source module <filename>Foo.lhs</filename> which
2200 imports another module <literal>Baz</literal>. Then the
2201 generated <filename>.depend</filename> file will contain
2202 the dependency:</para>
2204 <programlisting>Foo.o : Baz.hi</programlisting>
2206 <para>which says that the object file
2207 <filename>Foo.o</filename> depends on the interface file
2208 <filename>Baz.hi</filename> generated by compiling module
2209 <literal>Baz</literal>. The <filename>.depend</filename>
2210 file is automatically included by every Makefile.</para>
2215 <term><literal>binary-dist</literal></term>
2217 <para>make a binary distribution. This is the target we
2218 use to build the binary distributions of GHC and
2224 <term><literal>dist</literal></term>
2226 <para>make a source distribution. Note that this target
2227 does “make distclean” as part of its work;
2228 don't use it if you want to keep what you've built.</para>
2233 <para>Most <filename>Makefile</filename>s have targets other
2234 than these. You can discover them by looking in the
2235 <filename>Makefile</filename> itself.</para>
2239 <title>Using a project from the build tree</title>
2241 <para>If you want to build GHC (say) and just use it direct from
2242 the build tree without doing <literal>make install</literal>
2243 first, you can run the in-place driver script:
2244 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2246 <para> Do <emphasis>NOT</emphasis> use
2247 <filename>ghc/compiler/ghc</filename>, or
2248 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2249 scripts intended for installation, and contain hard-wired paths
2250 to the installed libraries, rather than the libraries in the
2253 <para>Happy can similarly be run from the build tree, using
2254 <filename>happy/src/happy-inplace</filename>, and similarly for
2255 Alex and Haddock.</para>
2259 <title>Fast Making</title>
2261 <indexterm><primary>fastmake</primary></indexterm>
2262 <indexterm><primary>dependencies, omitting</primary></indexterm>
2263 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2265 <para>Sometimes the dependencies get in the way: if you've made
2266 a small change to one file, and you're absolutely sure that it
2267 won't affect anything else, but you know that
2268 <command>make</command> is going to rebuild everything anyway,
2269 the following hack may be useful:</para>
2271 <programlisting>gmake FAST=YES</programlisting>
2273 <para>This tells the make system to ignore dependencies and just
2274 build what you tell it to. In other words, it's equivalent to
2275 temporarily removing the <filename>.depend</filename> file in
2276 the current directory (where <command>mkdependHS</command> and
2277 friends store their dependency information).</para>
2279 <para>A bit of history: GHC used to come with a
2280 <command>fastmake</command> script that did the above job, but
2281 GNU make provides the features we need to do it without
2282 resorting to a script. Also, we've found that fastmaking is
2283 less useful since the advent of GHC's recompilation checker (see
2284 the User's Guide section on "Separate Compilation").</para>
2288 <sect1 id="sec-makefile-arch">
2289 <title>The <filename>Makefile</filename> architecture</title>
2290 <indexterm><primary>makefile architecture</primary></indexterm>
2292 <para><command>make</command> is great if everything
2293 works—you type <command>gmake install</command> and lo! the
2294 right things get compiled and installed in the right places. Our
2295 goal is to make this happen often, but somehow it often doesn't;
2296 instead some weird error message eventually emerges from the
2297 bowels of a directory you didn't know existed.</para>
2299 <para>The purpose of this section is to give you a road-map to
2300 help you figure out what is going right and what is going
2304 <title>Debugging</title>
2306 <para>Debugging <filename>Makefile</filename>s is something of a
2307 black art, but here's a couple of tricks that we find
2308 particularly useful. The following command allows you to see
2309 the contents of any make variable in the context of the current
2310 <filename>Makefile</filename>:</para>
2312 <screen>$ make show VALUE=HS_SRCS</screen>
2314 <para>where you can replace <literal>HS_SRCS</literal> with the
2315 name of any variable you wish to see the value of.</para>
2317 <para>GNU make has a <option>-d</option> option which generates
2318 a dump of the decision procedure used to arrive at a conclusion
2319 about which files should be recompiled. Sometimes useful for
2320 tracking down problems with superfluous or missing
2321 recompilations.</para>
2325 <title>A small project</title>
2327 <para>To get started, let us look at the
2328 <filename>Makefile</filename> for an imaginary small
2329 <literal>fptools</literal> project, <literal>small</literal>.
2330 Each project in <literal>fptools</literal> has its own directory
2331 in <constant>FPTOOLS_TOP</constant>, so the
2332 <literal>small</literal> project will have its own directory
2333 <constant>FPOOLS_TOP/small/</constant>. Inside the
2334 <filename>small/</filename> directory there will be a
2335 <filename>Makefile</filename>, looking something like
2338 <indexterm><primary>Makefile, minimal</primary></indexterm>
2340 <programlisting># Makefile for fptools project "small"
2343 include $(TOP)/mk/boilerplate.mk
2345 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2348 include $(TOP)/target.mk</programlisting>
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>FPTOOLS_TOP/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>
2383 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
2386 <para>Why? Because the <filename>boilerplate.mk</filename>
2387 file needs to know where it is, so that it can, in turn,
2388 <literal>include</literal> other files. (Unfortunately,
2389 when an <literal>include</literal>d file does an
2390 <literal>include</literal>, the filename is treated relative
2391 to the directory in which <command>gmake</command> is being
2392 run, not the directory in which the
2393 <literal>include</literal>d sits.) In general,
2394 <emphasis>every file <filename>foo.mk</filename> assumes
2396 <filename>$(TOP)/mk/foo.mk</filename>
2397 refers to itself.</emphasis> It is up to the
2398 <filename>Makefile</filename> doing the
2399 <literal>include</literal> to ensure this is the case.</para>
2401 <para>Files intended for inclusion in other
2402 <filename>Makefile</filename>s are written to have the
2403 following property: <emphasis>after
2404 <filename>foo.mk</filename> is <literal>include</literal>d,
2405 it leaves <constant>TOP</constant> containing the same value
2406 as it had just before the <literal>include</literal>
2407 statement</emphasis>. In our example, this invariant
2408 guarantees that the <literal>include</literal> for
2409 <filename>target.mk</filename> will look in the same
2410 directory as that for <filename>boilerplate.mk</filename>.</para>
2414 <para> The second section defines the following standard
2415 <command>make</command> variables:
2416 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2417 (the source files from which is to be built), and
2418 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2419 (the executable binary to be built). We will discuss in
2420 more detail what the “standard variables” are,
2421 and how they affect what happens, in <xref
2422 linkend="sec-targets">.</para>
2424 <para>The definition for <constant>SRCS</constant> uses the
2425 useful GNU <command>make</command> construct
2426 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2427 which expands to a list of all the files matching the
2428 pattern <literal>pat</literal> in the current directory. In
2429 this example, <constant>SRCS</constant> is set to the list
2430 of all the <filename>.lhs</filename> and
2431 <filename>.c</filename> files in the directory. (Let's
2432 suppose there is one of each, <filename>Foo.lhs</filename>
2433 and <filename>Baz.c</filename>.)</para>
2437 <para>The last section includes a second file of standard
2439 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2440 It contains the rules that tell <command>gmake</command> how
2441 to make the standard targets (<xref
2442 linkend="sec-standard-targets">). Why, you ask, can't this
2443 standard code be part of
2444 <filename>boilerplate.mk</filename>? Good question. We
2445 discuss the reason later, in <xref
2446 linkend="sec-boiler-arch">.</para>
2448 <para>You do not <emphasis>have</emphasis> to
2449 <literal>include</literal> the
2450 <filename>target.mk</filename> file. Instead, you can write
2451 rules of your own for all the standard targets. Usually,
2452 though, you will find quite a big payoff from using the
2453 canned rules in <filename>target.mk</filename>; the price
2454 tag is that you have to understand what canned rules get
2455 enabled, and what they do (<xref
2456 linkend="sec-targets">).</para>
2460 <para>In our example <filename>Makefile</filename>, most of the
2461 work is done by the two <literal>include</literal>d files. When
2462 you say <command>gmake all</command>, the following things
2467 <para><command>gmake</command> figures out that the object
2468 files are <filename>Foo.o</filename> and
2469 <filename>Baz.o</filename>.</para>
2473 <para>It uses a boilerplate pattern rule to compile
2474 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2475 using a Haskell compiler. (Which one? That is set in the
2476 build configuration.)</para>
2480 <para>It uses another standard pattern rule to compile
2481 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2482 using a C compiler. (Ditto.)</para>
2486 <para>It links the resulting <filename>.o</filename> files
2487 together to make <literal>small</literal>, using the Haskell
2488 compiler to do the link step. (Why not use
2489 <command>ld</command>? Because the Haskell compiler knows
2490 what standard libraries to link in. How did
2491 <command>gmake</command> know to use the Haskell compiler to
2492 do the link, rather than the C compiler? Because we set the
2493 variable <constant>HS_PROG</constant> rather than
2494 <constant>C_PROG</constant>.)</para>
2498 <para>All <filename>Makefile</filename>s should follow the above
2499 three-section format.</para>
2503 <title>A larger project</title>
2505 <para>Larger projects are usually structured into a number of
2506 sub-directories, each of which has its own
2507 <filename>Makefile</filename>. (In very large projects, this
2508 sub-structure might be iterated recursively, though that is
2509 rare.) To give you the idea, here's part of the directory
2510 structure for the (rather large) GHC project:</para>
2512 <screen>$(FPTOOLS_TOP)/ghc/
2519 ...source files for documentation...
2522 ...source files for driver...
2525 parser/...source files for parser...
2526 renamer/...source files for renamer...
2529 <para>The sub-directories <filename>docs</filename>,
2530 <filename>driver</filename>, <filename>compiler</filename>, and
2531 so on, each contains a sub-component of GHC, and each has its
2532 own <filename>Makefile</filename>. There must also be a
2533 <filename>Makefile</filename> in
2534 <filename>$(FPTOOLS_TOP)/ghc</filename>.
2535 It does most of its work by recursively invoking
2536 <command>gmake</command> on the <filename>Makefile</filename>s
2537 in the sub-directories. We say that
2538 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2539 <filename>Makefile</filename></emphasis>, because it does little
2540 except organise its children, while the
2541 <filename>Makefile</filename>s in the sub-directories are all
2542 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2543 principle the sub-directories might themselves contain a
2544 non-leaf <filename>Makefile</filename> and several
2545 sub-sub-directories, but that does not happen in GHC.)</para>
2547 <para>The <filename>Makefile</filename> in
2548 <filename>ghc/compiler</filename> is considered a leaf
2549 <filename>Makefile</filename> even though the
2550 <filename>ghc/compiler</filename> has sub-directories, because
2551 these sub-directories do not themselves have
2552 <filename>Makefile</filename>s in them. They are just used to
2553 structure the collection of modules that make up GHC, but all
2554 are managed by the single <filename>Makefile</filename> in
2555 <filename>ghc/compiler</filename>.</para>
2557 <para>You will notice that <filename>ghc/</filename> also
2558 contains a directory <filename>ghc/mk/</filename>. It contains
2559 GHC-specific <filename>Makefile</filename> boilerplate code.
2560 More precisely:</para>
2564 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2565 at the top of <filename>ghc/Makefile</filename>, and of all
2566 the leaf <filename>Makefile</filename>s in the
2567 sub-directories. It in turn <literal>include</literal>s the
2568 main boilerplate file
2569 <filename>mk/boilerplate.mk</filename>.</para>
2573 <para><filename>ghc/mk/target.mk</filename> is
2574 <literal>include</literal>d at the bottom of
2575 <filename>ghc/Makefile</filename>, and of all the leaf
2576 <filename>Makefile</filename>s in the sub-directories. It
2577 in turn <literal>include</literal>s the file
2578 <filename>mk/target.mk</filename>.</para>
2582 <para>So these two files are the place to look for GHC-wide
2583 customisation of the standard boilerplate.</para>
2586 <sect2 id="sec-boiler-arch">
2587 <title>Boilerplate architecture</title>
2588 <indexterm><primary>boilerplate architecture</primary></indexterm>
2590 <para>Every <filename>Makefile</filename> includes a
2591 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2592 file at the top, and
2593 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2594 file at the bottom. In this section we discuss what is in these
2595 files, and why there have to be two of them. In general:</para>
2599 <para><filename>boilerplate.mk</filename> consists of:</para>
2603 <para><emphasis>Definitions of millions of
2604 <command>make</command> variables</emphasis> that
2605 collectively specify the build configuration. Examples:
2606 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2607 the options to feed to the Haskell compiler;
2608 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2609 the sub-directories to enable within the
2610 <literal>nofib</literal> project;
2611 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2612 the name of the Haskell compiler to use when compiling
2613 GHC in the <literal>ghc</literal> project.</para>
2617 <para><emphasis>Standard pattern rules</emphasis> that
2618 tell <command>gmake</command> how to construct one file
2619 from another.</para>
2623 <para><filename>boilerplate.mk</filename> needs to be
2624 <literal>include</literal>d at the <emphasis>top</emphasis>
2625 of each <filename>Makefile</filename>, so that the user can
2626 replace the boilerplate definitions or pattern rules by
2627 simply giving a new definition or pattern rule in the
2628 <filename>Makefile</filename>. <command>gmake</command>
2629 simply takes the last definition as the definitive one.</para>
2631 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2632 definitions, it is also quite common to
2633 <emphasis>augment</emphasis> them. For example, a
2634 <filename>Makefile</filename> might say:</para>
2636 <programlisting>SRC_HC_OPTS += -O</programlisting>
2638 <para>thereby adding “<option>-O</option>” to
2640 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2644 <para><filename>target.mk</filename> contains
2645 <command>make</command> rules for the standard targets
2646 described in <xref linkend="sec-standard-targets">. These
2647 rules are selectively included, depending on the setting of
2648 certain <command>make</command> variables. These variables
2649 are usually set in the middle section of the
2650 <filename>Makefile</filename> between the two
2651 <literal>include</literal>s.</para>
2653 <para><filename>target.mk</filename> must be included at the
2654 end (rather than being part of
2655 <filename>boilerplate.mk</filename>) for several tiresome
2661 <para><command>gmake</command> commits target and
2662 dependency lists earlier than it should. For example,
2663 <filename>target.mk</filename> has a rule that looks
2666 <programlisting>$(HS_PROG) : $(OBJS)
2667 $(HC) $(LD_OPTS) $< -o $@</programlisting>
2669 <para>If this rule was in
2670 <filename>boilerplate.mk</filename> then
2671 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2673 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2674 would not have their final values at the moment
2675 <command>gmake</command> encountered the rule. Alas,
2676 <command>gmake</command> takes a snapshot of their
2677 current values, and wires that snapshot into the rule.
2678 (In contrast, the commands executed when the rule
2679 “fires” are only substituted at the moment
2680 of firing.) So, the rule must follow the definitions
2681 given in the <filename>Makefile</filename> itself.</para>
2685 <para>Unlike pattern rules, ordinary rules cannot be
2686 overriden or replaced by subsequent rules for the same
2687 target (at least, not without an error message).
2688 Including ordinary rules in
2689 <filename>boilerplate.mk</filename> would prevent the
2690 user from writing rules for specific targets in specific
2695 <para>There are a couple of other reasons I've
2696 forgotten, but it doesn't matter too much.</para>
2703 <sect2 id="sec-boiler">
2704 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2705 <indexterm><primary>boilerplate.mk</primary></indexterm>
2707 <para>If you look at
2708 <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
2709 you will find that it consists of the following sections, each
2710 held in a separate file:</para>
2714 <term><filename>config.mk</filename>
2715 <indexterm><primary>config.mk</primary></indexterm>
2718 <para>is the build configuration file we discussed at
2719 length in <xref linkend="sec-build-config">.</para>
2724 <term><filename>paths.mk</filename>
2725 <indexterm><primary>paths.mk</primary></indexterm>
2728 <para>defines <command>make</command> variables for
2729 pathnames and file lists. This file contains code for
2730 automatically compiling lists of source files and deriving
2731 lists of object files from those. The results can be
2732 overriden in the <filename>Makefile</filename>, but in
2733 most cases the automatic setup should do the right
2736 <para>The following variables may be set in the
2737 <filename>Makefile</filename> to affect how the automatic
2738 source file search is done:</para>
2742 <term><literal>ALL_DIRS</literal>
2743 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
2746 <para>Set to a list of directories to search in
2747 addition to the current directory for source
2753 <term><literal>EXCLUDE_SRCS</literal>
2754 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
2757 <para>Set to a list of source files (relative to the
2758 current directory) to omit from the automatic
2759 search. The source searching machinery is clever
2760 enough to know that if you exclude a source file
2761 from which other sources are derived, then the
2762 derived sources should also be excluded. For
2763 example, if you set <literal>EXCLUDED_SRCS</literal>
2764 to include <filename>Foo.y</filename>, then
2765 <filename>Foo.hs</filename> will also be
2771 <term><literal>EXTRA_SRCS</literal>
2772 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
2775 <para>Set to a list of extra source files (perhaps
2776 in directories not listed in
2777 <literal>ALL_DIRS</literal>) that should be
2783 <para>The results of the automatic source file search are
2784 placed in the following make variables:</para>
2788 <term><literal>SRCS</literal>
2789 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2792 <para>All source files found, sorted and without
2793 duplicates, including those which might not exist
2794 yet but will be derived from other existing sources.
2795 <literal>SRCS</literal> <emphasis>can</emphasis> be
2796 overriden if necessary, in which case the variables
2797 below will follow suit.</para>
2802 <term><literal>HS_SRCS</literal>
2803 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2806 <para>all Haskell source files in the current
2807 directory, including those derived from other source
2808 files (eg. Happy sources also give rise to Haskell
2814 <term><literal>HS_OBJS</literal>
2815 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2818 <para>Object files derived from
2819 <literal>HS_SRCS</literal>.</para>
2824 <term><literal>HS_IFACES</literal>
2825 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2828 <para>Interface files (<literal>.hi</literal> files)
2829 derived from <literal>HS_SRCS</literal>.</para>
2834 <term><literal>C_SRCS</literal>
2835 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2838 <para>All C source files found.</para>
2843 <term><literal>C_OBJS</literal>
2844 <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>
2854 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2857 <para>All script source files found
2858 (<literal>.lprl</literal> files).</para>
2863 <term><literal>SCRIPT_OBJS</literal>
2864 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2867 <para><quote>object</quote> files derived from
2868 <literal>SCRIPT_SRCS</literal>
2869 (<literal>.prl</literal> files).</para>
2874 <term><literal>HSC_SRCS</literal>
2875 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2878 <para>All <literal>hsc2hs</literal> source files
2879 (<literal>.hsc</literal> files).</para>
2884 <term><literal>HAPPY_SRCS</literal>
2885 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2888 <para>All <literal>happy</literal> source files
2889 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2894 <term><literal>OBJS</literal>
2895 <indexterm><primary>OBJS</primary></indexterm>
2898 <para>the concatenation of
2899 <literal>$(HS_OBJS)</literal>,
2900 <literal>$(C_OBJS)</literal>, and
2901 <literal>$(SCRIPT_OBJS)</literal>.</para>
2906 <para>Any or all of these definitions can easily be
2907 overriden by giving new definitions in your
2908 <filename>Makefile</filename>.</para>
2910 <para>What, exactly, does <filename>paths.mk</filename>
2911 consider a <quote>source file</quote> to be? It's based
2912 on the file's suffix (e.g. <filename>.hs</filename>,
2913 <filename>.lhs</filename>, <filename>.c</filename>,
2914 <filename>.hy</filename>, etc), but this is the kind of
2915 detail that changes, so rather than enumerate the source
2916 suffices here the best thing to do is to look in
2917 <filename>paths.mk</filename>.</para>
2922 <term><filename>opts.mk</filename>
2923 <indexterm><primary>opts.mk</primary></indexterm>
2926 <para>defines <command>make</command> variables for option
2927 strings to pass to each program. For example, it defines
2928 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2929 the option strings to pass to the Haskell compiler. See
2930 <xref linkend="sec-suffix">.</para>
2935 <term><filename>suffix.mk</filename>
2936 <indexterm><primary>suffix.mk</primary></indexterm>
2939 <para>defines standard pattern rules—see <xref
2940 linkend="sec-suffix">.</para>
2945 <para>Any of the variables and pattern rules defined by the
2946 boilerplate file can easily be overridden in any particular
2947 <filename>Makefile</filename>, because the boilerplate
2948 <literal>include</literal> comes first. Definitions after this
2949 <literal>include</literal> directive simply override the default
2950 ones in <filename>boilerplate.mk</filename>.</para>
2953 <sect2 id="sec-suffix">
2954 <title>Pattern rules and options</title>
2955 <indexterm><primary>Pattern rules</primary></indexterm>
2958 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2959 defines standard <emphasis>pattern rules</emphasis> that say how
2960 to build one kind of file from another, for example, how to
2961 build a <filename>.o</filename> file from a
2962 <filename>.c</filename> file. (GNU <command>make</command>'s
2963 <emphasis>pattern rules</emphasis> are more powerful and easier
2964 to use than Unix <command>make</command>'s <emphasis>suffix
2965 rules</emphasis>.)</para>
2967 <para>Almost all the rules look something like this:</para>
2969 <programlisting>%.o : %.c
2971 $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
2973 <para>Here's how to understand the rule. It says that
2974 <emphasis>something</emphasis><filename>.o</filename> (say
2975 <filename>Foo.o</filename>) can be built from
2976 <emphasis>something</emphasis><filename>.c</filename>
2977 (<filename>Foo.c</filename>), by invoking the C compiler (path
2978 name held in <constant>$(CC)</constant>), passing to it
2979 the options <constant>$(CC_OPTS)</constant> and
2980 the rule's dependent file of the rule
2981 <literal>$<</literal> (<filename>Foo.c</filename> in
2982 this case), and putting the result in the rule's target
2983 <literal>$@</literal> (<filename>Foo.o</filename> in this
2986 <para>Every program is held in a <command>make</command>
2987 variable defined in <filename>mk/config.mk</filename>—look
2988 in <filename>mk/config.mk</filename> for the complete list. One
2989 important one is the Haskell compiler, which is called
2990 <constant>$(HC)</constant>.</para>
2992 <para>Every program's options are are held in a
2993 <command>make</command> variables called
2994 <constant><prog>_OPTS</constant>. the
2995 <constant><prog>_OPTS</constant> variables are
2996 defined in <filename>mk/opts.mk</filename>. Almost all of them
2997 are defined like this:</para>
2999 <programlisting>CC_OPTS = \
3000 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
3002 <para>The four variables from which
3003 <constant>CC_OPTS</constant> is built have the following
3008 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3010 <para>options passed to all C compilations.</para>
3015 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3017 <para>options passed to C compilations for way
3018 <literal><way></literal>. For example,
3019 <constant>WAY_mp_CC_OPTS</constant>
3020 gives options to pass to the C compiler when compiling way
3021 <literal>mp</literal>. The variable
3022 <constant>WAY_CC_OPTS</constant> holds
3023 options to pass to the C compiler when compiling the
3024 standard way. (<xref linkend="sec-ways"> dicusses
3025 multi-way compilation.)</para>
3030 <term><constant><module>_CC_OPTS</constant>:</term>
3032 <para>options to pass to the C compiler that are specific
3033 to module <literal><module></literal>. For example,
3034 <constant>SMap_CC_OPTS</constant> gives the
3035 specific options to pass to the C compiler when compiling
3036 <filename>SMap.c</filename>.</para>
3041 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3043 <para>extra options to pass to all C compilations. This
3044 is intended for command line use, thus:</para>
3046 <programlisting>gmake libHS.a EXTRA_CC_OPTS="-v"</programlisting>
3052 <sect2 id="sec-targets">
3053 <title>The main <filename>mk/target.mk</filename> file</title>
3054 <indexterm><primary>target.mk</primary></indexterm>
3056 <para><filename>target.mk</filename> contains canned rules for
3057 all the standard targets described in <xref
3058 linkend="sec-standard-targets">. It is complicated by the fact
3059 that you don't want all of these rules to be active in every
3060 <filename>Makefile</filename>. Rather than have a plethora of
3061 tiny files which you can include selectively, there is a single
3062 file, <filename>target.mk</filename>, which selectively includes
3063 rules based on whether you have defined certain variables in
3064 your <filename>Makefile</filename>. This section explains what
3065 rules you get, what variables control them, and what the rules
3066 do. Hopefully, you will also get enough of an idea of what is
3067 supposed to happen that you can read and understand any weird
3068 special cases yourself.</para>
3072 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3074 <para>If <constant>HS_PROG</constant> is defined,
3075 you get rules with the following targets:</para>
3079 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3081 <para>itself. This rule links
3082 <constant>$(OBJS)</constant> with the Haskell
3083 runtime system to get an executable called
3084 <constant>$(HS_PROG)</constant>.</para>
3089 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3092 <constant>$(HS_PROG)</constant> in
3093 <constant>$(bindir)</constant>.</para>
3102 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3104 <para>is similar to <constant>HS_PROG</constant>,
3105 except that the link step links
3106 <constant>$(C_OBJS)</constant> with the C
3107 runtime system.</para>
3112 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3114 <para>is similar to <constant>HS_PROG</constant>,
3115 except that it links
3116 <constant>$(LIB_OBJS)</constant> to make the
3117 library archive <constant>$(LIBRARY)</constant>,
3118 and <literal>install</literal> installs it in
3119 <constant>$(libdir)</constant>.</para>
3124 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3126 <para>…</para>
3131 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3133 <para>…</para>
3138 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3140 <para>If <constant>HS_SRCS</constant> is defined
3141 and non-empty, a rule for the target
3142 <literal>depend</literal> is included, which generates
3143 dependency information for Haskell programs. Similarly
3144 for <constant>C_SRCS</constant>.</para>
3149 <para>All of these rules are “double-colon” rules,
3152 <programlisting>install :: $(HS_PROG)
3153 ...how to install it...</programlisting>
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:
3294 <programlisting>%.$(way_)o : %.lhs
3295 $(HC) $(HC_OPTS) $< -o $@</programlisting>
3301 <para>You can invoke <command>make</command> with a
3302 particular <literal>way</literal> setting yourself, in order
3303 to build files related to a particular
3304 <literal>way</literal> in the current directory. eg.
3306 <screen>$ make way=p</screen>
3308 will build files for the profiling way only in the current
3315 <title>When the canned rule isn't right</title>
3317 <para>Sometimes the canned rule just doesn't do the right thing.
3318 For example, in the <literal>nofib</literal> suite we want the
3319 link step to print out timing information. The thing to do here
3320 is <emphasis>not</emphasis> to define
3321 <constant>HS_PROG</constant> or
3322 <constant>C_PROG</constant>, and instead define a special
3323 purpose rule in your own <filename>Makefile</filename>. By
3324 using different variable names you will avoid the canned rules
3325 being included, and conflicting with yours.</para>
3329 <sect1 id="building-docs">
3330 <title>Building the documentation</title>
3332 <sect2 id="pre-supposed-doc-tools">
3333 <title>Tools for building the Documentation</title>
3335 <para>The following additional tools are required if you want to
3336 format the documentation that comes with the
3337 <literal>fptools</literal> projects:</para>
3342 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3343 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3346 <para>Much of our documentation is written in SGML, using
3347 the DocBook DTD. Instructions on installing and
3348 configuring the DocBook tools are below.</para>
3354 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3355 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3358 <para>A decent TeX distribution is required if you want to
3359 produce printable documentation. We recomment teTeX,
3360 which includes just about everything you need.</para>
3366 <indexterm><primary>Haddock</primary></indexterm>
3369 <para>Haddock is a Haskell documentation tool that we use
3370 for automatically generating documentation from the
3371 library source code. It is an <literal>fptools</literal>
3372 project in itself. To build documentation for the
3373 libraries (<literal>fptools/libraries</literal>) you
3374 should check out and build Haddock in
3375 <literal>fptools/haddock</literal>. Haddock requires GHC
3383 <title>Installing the DocBook tools</title>
3386 <title>Installing the DocBook tools on Linux</title>
3388 <para>If you're on a recent RedHat system (7.0+), you probably
3389 have working DocBook tools already installed. The configure
3390 script should detect your setup and you're away.</para>
3392 <para>If you don't have DocBook tools installed, and you are
3393 using a system that can handle RedHat RPM packages, you can
3394 probably use the <ulink
3395 url="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3396 DocBook tools</ulink>, which is the most shrink-wrapped SGML
3397 suite that we could find. You need all the RPMs except for
3398 psgml (i.e. <filename>docbook</filename>,
3399 <filename>jade</filename>, <filename>jadetex</filename>,
3400 <filename>sgmlcommon</filename> and
3401 <filename>stylesheets</filename>). Note that most of these
3402 RPMs are architecture neutral, so are likely to be found in a
3403 <filename>noarch</filename> directory. The SuSE RPMs also
3404 work; the RedHat ones <emphasis>don't</emphasis> in RedHat 6.2
3405 (7.0 and later should be OK), but they are easy to fix: just
3407 <filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</filename>
3408 to <filename>/usr/lib/sgml/lib/dblib.dsl</filename>. </para>
3412 <title>Installing DocBook on FreeBSD</title>
3414 <para>On FreeBSD systems, the easiest way to get DocBook up
3415 and running is to install it from the ports tree or a
3416 pre-compiled package (packages are available from your local
3417 FreeBSD mirror site).</para>
3419 <para>To use the ports tree, do this:
3420 <screen>$ cd /usr/ports/textproc/docproj
3421 $ make install</screen>
3422 This installs the FreeBSD documentation project tools, which
3423 includes everything needed to format the GHC
3424 documentation.</para>
3428 <title>Installing from binaries on Windows</title>
3430 <para>It's a good idea to use Norman Walsh's <ulink
3431 url="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3432 notes</ulink> as a guide. You should get version 3.1 of
3433 DocBook, and note that his file <filename>test.sgm</filename>
3434 won't work, as it needs version 3.0. You should unpack Jade
3435 into <filename>\Jade</filename>, along with the entities,
3436 DocBook into <filename>\docbook</filename>, and the DocBook
3437 stylesheets into <filename>\docbook\stylesheets</filename> (so
3438 they actually end up in
3439 <filename>\docbook\stylesheets\docbook</filename>).</para>
3444 <title>Installing the DocBook tools from source</title>
3449 <para>Install <ulink
3450 url="http://openjade.sourceforge.net/">OpenJade</ulink>
3451 (Windows binaries are available as well as sources). If you
3452 want DVI, PS, or PDF then install JadeTeX from the
3453 <filename>dsssl</filename> subdirectory. (If you get the
3456 <screen>! LaTeX Error: Unknown option implicit=false' for package hyperref'.</screen>
3458 your version of <command>hyperref</command> is out of date;
3459 download it from CTAN
3460 (<filename>macros/latex/contrib/supported/hyperref</filename>),
3461 and make it, ensuring that you have first removed or renamed
3462 your old copy. If you start getting file not found errors
3463 when making the test for <command>hyperref</command>, you
3464 can abort at that point and proceed straight to
3465 <command>make install</command>, or enter them as
3466 <filename>../</filename><emphasis>filename</emphasis>.)</para>
3468 <para>Make links from <filename>virtex</filename> to
3469 <filename>jadetex</filename> and
3470 <filename>pdfvirtex</filename> to
3471 <filename>pdfjadetex</filename> (otherwise DVI, PostScript
3472 and PDF output will not work). Copy
3473 <filename>dsssl/*.{dtd,dsl}</filename> and
3474 <filename>catalog</filename> to
3475 <filename>/usr/[local/]lib/sgml</filename>.</para>
3479 <title>DocBook and the DocBook stylesheets</title>
3481 <para>Get a Zip of <ulink
3482 url="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ulink>
3483 and install the contents in
3484 <filename>/usr/[local/]/lib/sgml</filename>.</para>
3486 <para>Get the <ulink
3487 url="http://nwalsh.com/docbook/dsssl/">DocBook
3488 stylesheets</ulink> and install in
3489 <filename>/usr/[local/]lib/sgml/stylesheets</filename>
3490 (thereby creating a subdirectory docbook). For indexing,
3491 copy or link <filename>collateindex.pl</filename> from the
3492 DocBook stylesheets archive in <filename>bin</filename> into
3493 a directory on your <constant>PATH</constant>.</para>
3495 <para>Download the <ulink
3496 url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3497 entities</ulink> into
3498 <filename>/usr/[local/]lib/sgml</filename>.</para>
3504 <title>Configuring the DocBook tools</title>
3506 <para>Once the DocBook tools are installed, the configure script
3507 will detect them and set up the build system accordingly. If you
3508 have a system that isn't supported, let us know, and we'll try
3513 <title>Remaining problems</title>
3515 <para>If you install from source, you'll get a pile of warnings
3518 <screen>DTDDECL catalog entries are not supported</screen>
3520 every time you build anything. These can safely be ignored, but
3521 if you find them tedious you can get rid of them by removing all
3522 the <constant>DTDDECL</constant> entries from
3523 <filename>docbook.cat</filename>.</para>
3527 <title>Building the documentation</title>
3529 <para>To build documentation in a certain format, you can
3530 say, for example,</para>
3532 <screen>$ make html</screen>
3534 <para>to build HTML documentation below the current directory.
3535 The available formats are: <literal>dvi</literal>,
3536 <literal>ps</literal>, <literal>pdf</literal>,
3537 <literal>html</literal>, and <literal>rtf</literal>. Note that
3538 not all documentation can be built in all of these formats: HTML
3539 documentation is generally supported everywhere, and DocBook
3540 documentation might support the other formats (depending on what
3541 other tools you have installed).</para>
3543 <para>All of these targets are recursive; that is, saying
3544 <literal>make html</literal> will make HTML docs for all the
3545 documents recursively below the current directory.</para>
3547 <para>Because there are many different formats that the DocBook
3548 documentation can be generated in, you have to select which ones
3549 you want by setting the <literal>SGMLDocWays</literal> variable
3550 to a list of them. For example, in
3551 <filename>build.mk</filename> you might have a line:</para>
3553 <screen>SGMLDocWays = html ps</screen>
3555 <para>This will cause the documentation to be built in the requested
3556 formats as part of the main build (the default is not to build
3557 any documentation at all).</para>
3561 <title>Installing the documentation</title>
3563 <para>To install the documentation, use:</para>
3565 <screen>$ make install-docs</screen>
3567 <para>This will install the documentation into
3568 <literal>$(datadir)</literal> (which defaults to
3569 <literal>$(prefix)/share</literal>). The exception is HTML
3570 documentation, which goes into
3571 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3573 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3574 to a list of formats, the <literal>install-docs</literal> target
3575 won't do anything for SGML documentation.</para>
3581 <sect1 id="sec-porting-ghc">
3582 <title>Porting GHC</title>
3584 <para>This section describes how to port GHC to a currenly
3585 unsupported platform. There are two distinct
3586 possibilities:</para>
3590 <para>The hardware architecture for your system is already
3591 supported by GHC, but you're running an OS that isn't
3592 supported (or perhaps has been supported in the past, but
3593 currently isn't). This is the easiest type of porting job,
3594 but it still requires some careful bootstrapping. Proceed to
3595 <xref linkend="sec-booting-from-hc">.</para>
3599 <para>Your system's hardware architecture isn't supported by
3600 GHC. This will be a more difficult port (though by comparison
3601 perhaps not as difficult as porting gcc). Proceed to <xref
3602 linkend="unregisterised-porting">.</para>
3606 <sect2 id="sec-booting-from-hc">
3607 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3609 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3610 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3611 <indexterm><primary>porting GHC</primary></indexterm>
3613 <para>Bootstrapping GHC on a system without GHC already
3614 installed is achieved by taking the intermediate C files (known
3615 as HC files) from a GHC compilation on a supported system to the
3616 target machine, and compiling them using gcc to get a working
3619 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3620 from C. We recommend using GHC 6.0.1 or
3621 later.</emphasis></para>
3623 <para>HC files are platform-dependent, so you have to get a set
3624 that were generated on similar hardware. There may be some
3625 supplied on the GHC download page, otherwise you'll have to
3626 compile some up yourself, or start from
3627 <emphasis>unregisterised</emphasis> HC files - see <xref
3628 linkend="unregisterised-porting">.</para>
3630 <para>The following steps should result in a working GHC build
3631 with full libraries:</para>
3635 <para>Unpack the HC files on top of a fresh source tree
3636 (make sure the source tree version matches the version of
3637 the HC files <emphasis>exactly</emphasis>!). This will
3638 place matching <filename>.hc</filename> files next to the
3639 corresponding Haskell source (<filename>.hs</filename> or
3640 <filename>.lhs</filename>) in the compiler subdirectory
3641 <filename>ghc/compiler</filename> and in the libraries
3642 (subdirectories of <filename>hslibs</filename> and
3643 <literal>libraries</literal>).</para>
3647 <para>The actual build process is fully automated by the
3648 <filename>hc-build</filename> script located in the
3649 <filename>distrib</filename> directory. If you eventually
3650 want to install GHC into the directory
3651 <replaceable>dir</replaceable>, the following
3652 command will execute the whole build process (it won't
3653 install yet):</para>
3655 <screen>foo% distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
3656 <indexterm><primary>--hc-build</primary></indexterm>
3658 <para>By default, the installation directory is
3659 <filename>/usr/local</filename>. If that is what you want,
3660 you may omit the argument to <filename>hc-build</filename>.
3661 Generally, any option given to <filename>hc-build</filename>
3662 is passed through to the configuration script
3663 <filename>configure</filename>. If
3664 <filename>hc-build</filename> successfully completes the
3665 build process, you can install the resulting system, as
3668 <screen>foo% make install</screen>
3673 <sect2 id="unregisterised-porting">
3674 <title>Porting GHC to a new architecture</title>
3676 <para>The first step in porting to a new architecture is to get
3677 an <firstterm>unregisterised</firstterm> build working. An
3678 unregisterised build is one that compiles via vanilla C only.
3679 By contrast, a registerised build uses the following
3680 architecture-specific hacks for speed:</para>
3684 <para>Global register variables: certain abstract machine
3685 <quote>registers</quote> are mapped to real machine
3686 registers, depending on how many machine registers are
3688 <filename>ghc/includes/MachRegs.h</filename>).</para>
3692 <para>Assembly-mangling: when compiling via C, we feed the
3693 assembly generated by gcc though a Perl script known as the
3694 <firstterm>mangler</firstterm> (see
3695 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3696 mangler rearranges the assembly to support tail-calls and
3697 various other optimisations.</para>
3701 <para>In an unregisterised build, neither of these hacks are
3702 used — the idea is that the C code generated by the
3703 compiler should compile using gcc only. The lack of these
3704 optimisations costs about a factor of two in performance, but
3705 since unregisterised compilation is usually just a step on the
3706 way to a full registerised port, we don't mind too much.</para>
3708 <para>Notes on GHC portability in general: we've tried to stick
3709 to writing portable code in most parts of the system, so it
3710 should compile on any POSIXish system with gcc, but in our
3711 experience most systems differ from the standards in one way or
3712 another. Deal with any problems as they arise - if you get
3713 stuck, ask the experts on
3714 <email>glasgow-haskell-users@haskell.org</email>.</para>
3716 <para>Lots of useful information about the innards of GHC is
3717 available in the <ulink
3718 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3719 Commentary</ulink>, which might be helpful if you run into some
3720 code which needs tweaking for your system.</para>
3723 <title>Cross-compiling to produce an unregisterised GHC</title>
3725 <para>In this section, we explain how to bootstrap GHC on a
3726 new platform, using unregisterised intermediate C files. We
3727 haven't put a great deal of effort into automating this
3728 process, for two reasons: it is done very rarely, and the
3729 process usually requires human intervention to cope with minor
3730 porting issues anyway.</para>
3732 <para>The following step-by-step instructions should result in
3733 a fully working, albeit unregisterised, GHC. Firstly, you
3734 need a machine that already has a working GHC (we'll call this
3735 the <firstterm>host</firstterm> machine), in order to
3736 cross-compile the intermediate C files that we will use to
3737 bootstrap the compiler on the <firstterm>target</firstterm>
3742 <para>On the target machine:</para>
3746 <para>Unpack a source tree (preferably a released
3747 version). We will call the path to the root of this
3748 tree <replaceable>T</replaceable>.</para>
3752 <screen>$ cd <replaceable>T</replaceable>
3753 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
3755 <para>You might need to update
3756 <filename>configure.in</filename> to recognise the new
3757 architecture, and re-generate
3758 <filename>configure</filename> with
3759 <literal>autoreconf</literal>.</para>
3763 <screen>$ cd <replaceable>T</replaceable>/ghc/includes
3764 $ make config.h</screen>
3770 <para>On the host machine:</para>
3774 <para>Unpack a source tree (same released version). Call
3775 this directory <replaceable>H</replaceable>.</para>
3779 <screen>$ cd <replaceable>H</replaceable>
3780 $ ./configure</screen>
3785 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3786 with the following contents:</para>
3788 <programlisting>GhcUnregisterised = YES
3789 GhcLibHcOpts = -O -H32m -keep-hc-files
3792 GhcWithNativeCodeGen = NO
3793 GhcWithInterpreter = NO
3794 GhcStage1HcOpts = -O -H32m -fasm
3795 GhcStage2HcOpts = -O -fvia-C -keep-hc-files</programlisting>
3800 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3803 <para>change <literal>TARGETPLATFORM</literal>
3804 appropriately, and set the variables involving
3805 <literal>TARGET</literal> to the correct values for
3806 the target platform. This step is necessary because
3807 currently <literal>configure</literal> doesn't cope
3808 with specifying different values for the
3809 <literal>--host</literal> and
3810 <literal>--target</literal> flags.</para>
3813 <para>copy <literal>LeadingUnderscore</literal>
3814 setting from target.</para>
3821 <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
3823 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3824 Note that we are building on the host machine, using the
3825 target machine's <literal>config.h</literal> file. This
3826 is so that the intermediate C files generated here will
3827 be suitable for compiling on the target system.</para>
3832 <para>Touch <literal>config.h</literal>, just to make
3833 sure it doesn't get replaced during the build:</para>
3834 <screen>$ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
3838 <para>Now build the compiler:</para>
3839 <screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3840 $ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
3841 <para>Don't worry if the build falls over in the RTS, we
3842 don't need the RTS yet.</para>
3846 <screen>$ cd <replaceable>H</replaceable>/libraries
3847 $ make boot && make</screen>
3851 <screen>$ cd <replaceable>H</replaceable>/ghc
3852 $ make boot stage=2 && make stage=2</screen>
3856 <screen>$ cd <replaceable>H</replaceable>/ghc/utils
3858 $ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
3859 EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
3863 <screen>$ cd <replaceable>H</replaceable>
3864 $ make hc-file-bundle Project=Ghc</screen>
3869 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3870 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3876 <para>On the target machine:</para>
3878 <para>At this stage we simply need to bootstrap a compiler
3879 from the intermediate C files we generated above. The
3880 process of bootstrapping from C files is automated by the
3881 script in <literal>distrib/hc-build</literal>, and is
3882 described in <xref linkend="sec-booting-from-hc">.</para>
3884 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
3886 <para>However, since this is a bootstrap on a new machine,
3887 the automated process might not run to completion the
3888 first time. For that reason, you might want to treat the
3889 <literal>hc-build</literal> script as a list of
3890 instructions to follow, rather than as a fully automated
3891 script. This way you'll be able to restart the process
3892 part-way through if you need to fix anything on the
3895 <para>Don't bother with running
3896 <literal>make install</literal> in the newly
3897 bootstrapped tree; just use the compiler in that tree to
3898 build a fresh compiler from scratch, this time without
3899 booting from C files. Before doing this, you might want
3900 to check that the bootstrapped compiler is generating
3901 working binaries:</para>
3903 <screen>$ cat >hello.hs
3904 main = putStrLn "Hello World!\n"
3906 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3908 Hello World!</screen>
3910 <para>Once you have the unregisterised compiler up and
3911 running, you can use it to start a registerised port. The
3912 following sections describe the various parts of the
3913 system that will need architecture-specific tweaks in
3914 order to get a registerised build going.</para>
3921 <title>Porting the RTS</title>
3923 <para>The following files need architecture-specific code for a
3924 registerised build:</para>
3928 <term><filename>ghc/includes/MachRegs.h</filename>
3929 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
3932 <para>Defines the STG-register to machine-register
3933 mapping. You need to know your platform's C calling
3934 convention, and which registers are generally available
3935 for mapping to global register variables. There are
3936 plenty of useful comments in this file.</para>
3940 <term><filename>ghc/includes/TailCalls.h</filename>
3941 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
3944 <para>Macros that cooperate with the mangler (see <xref
3945 linkend="sec-mangler">) to make proper tail-calls
3950 <term><filename>ghc/rts/Adjustor.c</filename>
3951 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
3955 <literal>foreign import "wrapper"</literal>
3957 <literal>foreign export dynamic</literal>).
3958 Not essential for getting GHC bootstrapped, so this file
3959 can be deferred until later if necessary.</para>
3963 <term><filename>ghc/rts/StgCRun.c</filename>
3964 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
3967 <para>The little assembly layer between the C world and
3968 the Haskell world. See the comments and code for the
3969 other architectures in this file for pointers.</para>
3973 <term><filename>ghc/rts/MBlock.h</filename>
3974 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
3976 <term><filename>ghc/rts/MBlock.c</filename>
3977 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
3980 <para>These files are really OS-specific rather than
3981 architecture-specific. In <filename>MBlock.h</filename>
3982 is specified the absolute location at which the RTS
3983 should try to allocate memory on your platform (try to
3984 find an area which doesn't conflict with code or dynamic
3985 libraries). In <filename>Mblock.c</filename> you might
3986 need to tweak the call to <literal>mmap()</literal> for
3993 <sect3 id="sec-mangler">
3994 <title>The mangler</title>
3996 <para>The mangler is an evil Perl-script
3997 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
3998 rearranges the assembly code output from gcc to do two main
4003 <para>Remove function prologues and epilogues, and all
4004 movement of the C stack pointer. This is to support
4005 tail-calls: every code block in Haskell code ends in an
4006 explicit jump, so we don't want the C-stack overflowing
4007 while we're jumping around between code blocks.</para>
4010 <para>Move the <firstterm>info table</firstterm> for a
4011 closure next to the entry code for that closure. In
4012 unregisterised code, info tables contain a pointer to the
4013 entry code, but in registerised compilation we arrange
4014 that the info table is shoved right up against the entry
4015 code, and addressed backwards from the entry code pointer
4016 (this saves a word in the info table and an extra
4017 indirection when jumping to the closure entry
4022 <para>The mangler is abstracted to a certain extent over some
4023 architecture-specific things such as the particular assembler
4024 directives used to herald symbols. Take a look at the
4025 definitions for other architectures and use these as a
4026 starting point.</para>
4030 <title>The splitter</title>
4032 <para>The splitter is another evil Perl script
4033 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
4034 cooperates with the mangler to support object splitting.
4035 Object splitting is what happens when the
4036 <option>-split-objs</option> option is passed to GHC: the
4037 object file is split into many smaller objects. This feature
4038 is used when building libraries, so that a program statically
4039 linked against the library will pull in less of the
4042 <para>The splitter has some platform-specific stuff; take a
4043 look and tweak it for your system.</para>
4047 <title>The native code generator</title>
4049 <para>The native code generator isn't essential to getting a
4050 registerised build going, but it's a desirable thing to have
4051 because it can cut compilation times in half. The native code
4052 generator is described in some detail in the <ulink
4053 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
4054 commentary</ulink>.</para>
4060 <para>To support GHCi, you need to port the dynamic linker
4061 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
4062 currently supports the ELF and PEi386 object file formats - if
4063 your platform uses one of these then things will be
4064 significantly easier. The majority of Unix platforms use the
4065 ELF format these days. Even so, there are some
4066 machine-specific parts of the ELF linker: for example, the
4067 code for resolving particular relocation types is
4068 machine-specific, so some porting of this code to your
4069 architecture will probaly be necessary.</para>
4071 <para>If your system uses a different object file format, then
4072 you have to write a linker — good luck!</para>
4078 <sect1 id="sec-build-pitfalls">
4079 <title>Known pitfalls in building Glasgow Haskell
4081 <indexterm><primary>problems, building</primary></indexterm>
4082 <indexterm><primary>pitfalls, in building</primary></indexterm>
4083 <indexterm><primary>building pitfalls</primary></indexterm></title>
4086 WARNINGS about pitfalls and known “problems”:
4095 One difficulty that comes up from time to time is running out of space
4096 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
4097 compensate for the vagaries of different sysadmin approaches to temp
4099 <indexterm><primary>tmp, running out of space in</primary></indexterm>
4101 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
4102 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
4105 The best way around it is to say
4107 <programlisting>export TMPDIR=<dir></programlisting>
4109 in your <filename>build.mk</filename> file.
4110 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
4119 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
4120 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
4128 When compiling via C, you'll sometimes get “warning: assignment from
4129 incompatible pointer type” out of GCC. Harmless.
4136 Similarly, <command>ar</command>chiving warning messages like the following are not
4139 <screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
4140 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
4149 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
4150 get an “Out of heap space” error message. These can vary with the
4151 vagaries of different systems, it seems. The solution is simple:
4158 If you're compiling with GHC 4.00 or later, then the
4159 <emphasis>maximum</emphasis> heap size must have been reached. This
4160 is somewhat unlikely, since the maximum is set to 64M by default.
4161 Anyway, you can raise it with the
4162 <option>-optCrts-M<size></option> flag (add this flag to
4163 <constant><module>_HC_OPTS</constant>
4164 <command>make</command> variable in the appropriate
4165 <filename>Makefile</filename>).
4172 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4181 and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"> for information about
4182 <constant><module>_HC_OPTS</constant>.)
4184 Alternatively, just cut to the chase:
4186 <screen>% cd ghc/compiler
4187 % make EXTRA_HC_OPTS=-optCrts-M128M</screen>
4195 If you try to compile some Haskell, and you get errors from GCC about
4196 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4197 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4199 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4200 this bug also suggests that you have an old GCC.
4208 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4211 <screen>% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4212 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4214 ? # or, on some machines: ar s $i
4218 We'd be interested to know if this is still necessary.
4226 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4227 a bit from one Unix to another. One particular gotcha is macro calls
4231 <programlisting>SLIT("Hello, world")</programlisting>
4234 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4235 arguments, so you get
4238 <screen>:731: macro `SLIT' used with too many (2) args</screen>
4241 Alas, <command>cpp</command> doesn't tell you the offending file!
4243 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4254 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
4256 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
4257 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
4260 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
4262 <para> The build system is built around Unix-y makefiles. Because it's not native,
4263 the Windows situation for building GHC is particularly confusing. This section
4264 tries to clarify, and to establish terminology.</para>
4266 <sect3 id="ghc-mingw"><title>MinGW</title>
4268 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4269 is a collection of header
4270 files and import libraries that allow one to use <command>gcc</command> and produce
4271 native Win32 programs that do not rely on any third-party DLLs. The
4272 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4273 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4277 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
4282 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
4284 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
4285 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
4286 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
4287 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
4288 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
4292 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
4293 compile code that has access to all of Posix. The price is that the executables must be
4294 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
4295 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4296 does not change, but the implementation certainly does. Even the interfaces to functions
4297 it exports seem to change occasionally. </para>
4301 MSYS is a fork of the Cygwin tree, so they
4302 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
4303 through fewer layers, so MSYS is quite a bit faster too.
4306 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
4307 compile binaries that run with no DLL support, on any Win32 system.
4308 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
4309 <command>cvs</command>, <command>ssh</command> etc. To get these, you have to download the
4310 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
4312 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
4313 <command>ssh</command> and so on),
4314 not by programs compiled under MSYS.
4322 <sect3><title>Targeting MinGW</title>
4324 <para>We want GHC to compile programs that work on any Win32 system. Hence:
4327 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
4328 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
4329 will work on any system, but it also means that the programs GHC compiles do not have access
4330 to all of Posix. In particular, they cannot import the (Haskell) Posix
4331 library; they have to do
4332 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
4333 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4337 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
4338 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4341 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
4342 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
4343 that targets Cygwin instead. The up-side of GHC-cygwin is
4344 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4345 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
4348 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
4349 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
4350 GHC; both work fine, though MSYS is rather lighter weight.</para>
4352 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
4353 uses the <command>gcc</command> that you specify using the
4354 <option>--with-gcc</option> flag when you run
4355 <command>configure</command> (see below).
4356 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
4357 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
4358 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
4359 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
4360 used to glom together .o files into a bigger .o file, or a .a file,
4361 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4362 Cygwin and MinGW use the same .o file format. So its ok.
4366 <sect3><title> File names </title>
4368 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
4372 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
4373 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
4375 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
4376 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
4377 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
4379 <programlisting>foogle -B/c/tmp/baz</programlisting>
4380 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
4384 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
4386 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
4392 <sect3><title>Host System vs Target System</title>
4395 In the source code you'll find various ifdefs looking like:
4396 <programlisting>#ifdef mingw32_HOST_OS
4398 #endif</programlisting>
4400 <programlisting>#ifdef mingw32_TARGET_OS
4402 #endif</programlisting>
4403 These macros are set by the configure script (via the file config.h).
4404 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4407 <para>The "host" system is the one on which GHC itself will be run.</para>
4410 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
4413 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4414 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4421 <sect2><title>Wrapper scripts</title>
4424 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
4425 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
4426 GHC itself as an example:
4429 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
4430 paths to the front of the source file <filename>ghc.sh</filename>,
4431 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
4432 where to find its supporting files.
4436 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
4437 native Windows shell <command>cmd</command> (e.g. limits on the length
4438 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
4439 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
4440 and from that figures out where the supporting files are.
4443 (You can find the layout of GHC's supporting files in the
4444 section "Layout of installed files" of Section 2 of the GHC user guide.)
4447 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
4448 execute a program that has just been built in a build tree. The difference is that the
4449 layout of the supporting files is different.
4450 In this case, whether on Windows or Unix, we always use a shell script. This works OK
4451 on Windows because the script is executed by MSYS or Cygwin, which don't have the
4452 shortcomings of the native Windows <command>cmd</command> shell.
4459 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
4462 This section gives detailed instructions for how to build
4463 GHC from source on your Windows machine. Similar instructions for
4464 installing and running GHC may be found in the user guide. In general,
4465 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4468 Make sure you read the preceding section on platforms (<xref linkend="platforms">)
4469 before reading section.
4470 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
4471 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
4474 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
4477 MSYS is a lightweight alternative to Cygwin.
4478 You don't need MSYS to <emphasis>use</emphasis> GHC,
4479 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
4480 Here's how to install MSYS.
4483 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
4484 download the following (of course, the version numbers will differ):
4486 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
4488 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
4489 This provides <command>make</command>, <command>autoconf</command>,
4490 <command>ssh</command>, <command>cvs</command> and probably more besides.
4493 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
4497 Set the following environment variables
4499 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path. (Of course, the version number may differ.)
4502 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
4503 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
4506 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
4509 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
4513 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
4520 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
4521 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
4522 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
4523 file has too-liberal permissinos.
4528 <para>Here are some points to bear in mind when using MSYS:
4530 <listitem> <para> MSYS does some kind of special magic to binaries stored in
4531 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
4532 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
4533 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
4534 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
4535 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
4537 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
4541 Win32 has a <command>find</command> command which is not the same as MSYS's find.
4542 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4543 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4544 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4545 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4549 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
4550 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
4551 bzip'd dump.</para></listitem>
4557 <sect2><title>Installing and configuring Cygwin</title>
4559 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4560 The installation process is straightforward; we install it in <filename>c:/cygwin</filename>.
4561 During the installation dialogue, make sure that you select all of the following:
4562 <command>cvs</command>,
4563 <command>openssh</command>,
4564 <command>autoconf</command>,
4565 <command>binutils</command> (includes ld and (I think) ar),
4566 <command>gcc</command>,
4567 <command>flex</command>,
4568 <command>make</command>.
4569 If you miss out any of these, strange things will happen to you. To see thse packages,
4570 click on the "View" button in the "Select Packages"
4571 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
4572 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
4574 <para> Now set the following user environment variables:
4577 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4578 <constant>PATH</constant></para></listitem>
4582 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
4583 don't do this you get very weird messages when you type
4584 <command>make</command>, such as:
4585 <screen>/c: /c: No such file or directory</screen>
4589 <listitem><para> Set <constant>SHELL</constant> to
4590 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
4591 <constant>SHELL</constant> is what you get.
4594 <listitem><para> Set <constant>HOME</constant> to point to your
4595 home directory. This is where, for example,
4596 <command>bash</command> will look for your <filename>.bashrc</filename>
4597 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4603 There are a few other things to do:
4607 By default, cygwin provides the command shell <filename>ash</filename>
4608 as <filename>sh.exe</filename>. We have often seen build-system problems that
4609 turn out to be due to bugs in <filename>ash</filename>
4611 and length of command lines). On the other hand <filename>bash</filename> seems
4613 So, in <filename>cygwin/bin</filename>
4614 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4615 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4616 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4617 you can't rename a running program!
4623 Some script files used in the make system start with "<command>#!/bin/perl</command>",
4624 (and similarly for <command>sh</command>). Notice the hardwired path!
4625 So you need to ensure that your <filename>/bin</filename> directory has the following
4628 <listitem> <para><command>sh</command></para></listitem>
4629 <listitem> <para><command>perl</command></para></listitem>
4630 <listitem> <para><command>cat</command></para></listitem>
4632 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
4633 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
4634 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
4635 (You can discover where your Cygwin
4636 root directory <filename>/</filename> is by typing <command>mount</command>.)
4637 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
4638 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4639 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4645 <para>Finally, here are some things to be aware of when using Cygwin:
4647 <listitem> <para>Cygwin doesn't deal well with filenames that include
4648 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4652 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4653 magical text in it. So other programs that don't use Cygwin's
4654 I/O libraries won't recognise such files as symlinks.
4655 In particular, programs compiled by GHC are meant to be runnable
4656 without having Cygwin, so they don't use the Cygwin library, so
4657 they don't recognise symlinks.
4661 See the notes in <xref linkend="msys-install"> about <command>find</command> and <command>bzip</command>,
4662 which apply to Cygwin too.
4670 <sect2 id="configure-ssh"><title>Configuring SSH</title>
4672 <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
4673 you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
4674 (not ssh) in the Cygwin list of applications!</para>
4676 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
4680 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
4681 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
4682 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
4683 and run it as follows:
4684 <screen>c:\tmp> set CYGWIN32=tty
4685 c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
4688 <listitem><para> (Cygwin-only problem, I think.)
4689 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
4690 To determine your home directory <command>ssh</command> first looks in
4691 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
4692 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
4693 the setting of the environment variable $HOME</emphasis>. If the home directory is
4694 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
4695 <programlisting>ssh -v cvs.haskell.org</programlisting>
4696 which makes <command>ssh</command> print out information about its activity.
4698 <para> You can fix this problem, either by correcting the home-directory field in
4699 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
4700 you do that, <command>ssh</command> uses the $HOME environment variable instead.
4706 <para>To protect your
4707 <literal>.ssh</literal> from access by anyone else,
4708 right-click your <literal>.ssh</literal> directory, and
4709 select <literal>Properties</literal>. If you are not on
4710 the access control list, add yourself, and give yourself
4711 full permissions (the second panel). Remove everyone else
4712 from the access control list. Don't leave them there but
4713 deny them access, because 'they' may be a list that
4714 includes you!</para>
4718 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4719 you to have Unix permissions 600 (read/write for owner only)
4720 on the <literal>.ssh/identity</literal> file, else it
4721 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4722 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4723 The solution seems to be to set the $CYGWIN environment
4724 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4725 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4726 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4733 <sect2><title>Other things you need to install</title>
4735 <para>You have to install the following other things to build GHC, listed below.</para>
4737 <para>On Windows you often install executables in directories with spaces, such as
4738 "<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
4739 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
4740 to put binaries for all tools in places with no spaces in their path.
4741 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
4742 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
4743 provided they are in your path.
4747 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4748 This is what you will use to compile GHC. Add it in your
4749 <constant>PATH</constant>: the installer tells you the path element
4750 you need to add upon completion.
4756 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4757 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
4758 build it from the source distribution using
4759 <programlisting>./configure
4761 make install</programlisting>
4762 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
4764 Make sure the installation directory is in your
4765 <constant>PATH</constant>.
4770 <para>Install Alex. This can be done by building from the
4771 source distribution in the same way as Happy. Sources are
4772 available from <ulink
4773 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4777 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4778 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">).
4779 Just pick up a mingw bundle at
4780 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4781 We install it in <filename>c:/mingw</filename>.
4783 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4784 They are only going to get used by explicit access (via the --with-gcc flag you
4785 give to <command>configure</command> later). If you do add them to your path
4786 you are likely to get into a mess because their names overlap with Cygwin binaries.
4792 <para>We use <command>emacs</command> a lot, so we install that too.
4793 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4794 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4795 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4796 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4797 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4798 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4804 <para> Finally, check out a copy of GHC sources from
4805 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
4812 <sect2><title>Building GHC</title>
4815 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
4816 the bullets below only tell
4817 you about Windows-specific wrinkles.</para>
4821 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
4822 you'll get an error when you run <filename>./configure</filename>:
4825 creating mk/config.h
4826 mk/config.h is unchanged
4828 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4829 ./configure: ./configure: No such file or directory
4830 configure: error: ./configure failed for ghc</screen>
4834 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
4835 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
4837 <screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
4838 Solution: delete <filename>configure</filename> first.
4843 After <command>autoreconf</command> run <command>./configure</command> in
4844 <filename>fptools/</filename> thus:
4846 <screen>./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
4847 This is the point at which you specify that you are building GHC-mingw
4848 (see <xref linkend="ghc-mingw">). </para>
4850 <para> Both these options are important! It's possible to get into
4851 trouble using the wrong C compiler!</para>
4853 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4854 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4855 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4856 understand a Cygwin path. For example, if you
4857 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4858 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4859 time it tries to invoke it. Worse, the failure comes with
4860 no error message whatsoever. GHC simply fails silently when first invoked,
4861 typically leaving you with this:
4862 <screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4863 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4864 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4865 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4866 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4867 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4868 -optc-fomit-frame-pointer -O2 -static
4869 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4870 make[2]: *** [Adjustor.o] Error 1
4871 make[1]: *** [all] Error 1
4872 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4873 make: *** [all] Error 1</screen>
4878 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
4879 you'll have to do something more like:
4880 <screen>./configure --with-gcc=...the Cygwin gcc...</screen>
4885 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4886 This file occasionally remembers out-of-date configuration information, which
4887 can be really confusing.
4891 <listitem><para> You almost certainly want to set
4892 <programlisting>SplitObjs = NO</programlisting>
4893 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
4894 This tells the build system not to split each library into a myriad of little object files, one
4895 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4896 it dramatically increases the time taken to build the libraries in the first place.
4900 <listitem><para> Do not attempt to build the documentation.
4901 It needs all kinds of wierd Jade stuff that we haven't worked out for
4902 Win32.</para></listitem>
projects / ghc-hetmet.git / blob