1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5 <article id="building-guide">
9 <title>Building the Glasgow Functional Programming Tools Suite</title>
10 <author><othername>The GHC Team</othername></author>
11 <address><email>glasgow-haskell-{users,bugs}@haskell.org</email></address>
14 <para>The Glasgow fptools suite is a collection of Functional
15 Programming related tools, including the Glasgow Haskell
16 Compiler (GHC). The source code for the whole suite is kept in
17 a single CVS repository and shares a common build and
18 installation system.</para>
20 <para>This guide is intended for people who want to build or
21 modify programs from the Glasgow <literal>fptools</literal>
22 suite (as distinct from those who merely want to
23 <emphasis>run</emphasis> them). Installation instructions are
24 now provided in the user guide.</para>
26 <para>The bulk of this guide applies to building on Unix
27 systems; see <xref linkend="winbuild"/> for Windows notes.</para>
33 <sect1 id="sec-getting">
34 <title>Getting the sources</title>
36 <para>You can get your hands on the <literal>fptools</literal>
42 <term><indexterm><primary>Source
43 distributions</primary></indexterm>Source distributions</term>
45 <para>You have a supported platform, but (a) you like
46 the warm fuzzy feeling of compiling things yourself;
47 (b) you want to build something ``extra”—e.g., a
48 set of libraries with strictness-analysis turned off; or
49 (c) you want to hack on GHC yourself.</para>
51 <para>A source distribution contains complete sources for
52 one or more projects in the <literal>fptools</literal>
53 suite. Not only that, but the more awkward
54 machine-independent steps are done for you. For example, if
56 <command>happy</command><indexterm><primary>happy</primary></indexterm>
57 you'll find it convenient that the source distribution
58 contains the result of running <command>happy</command> on
59 the parser specifications. If you don't want to alter the
60 parser then this saves you having to find and install
61 <command>happy</command>. You will still need a working
62 version of GHC (version 5.x or later) on your machine in
63 order to compile (most of) the sources, however.</para>
68 <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
70 <para>We make releases infrequently. If you want more
71 up-to-the minute (but less tested) source code then you need
72 to get access to our CVS repository.</para>
74 <para>All the <literal>fptools</literal> source code is held
75 in a CVS repository. CVS is a pretty good source-code
76 control system, and best of all it works over the
79 <para>The repository holds source code only. It holds no
80 mechanically generated files at all. So if you check out a
81 source tree from CVS you will need to install every utility
82 so that you can build all the derived files from
85 <para>More information about our CVS repository can be found
86 in <xref linkend="sec-cvs"/>.</para>
91 <para>If you are going to do any building from sources (either
92 from a source distribution or the CVS repository) then you need to
93 read all of this manual in detail.</para>
97 <title>Using the CVS repository</title>
99 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
100 sources for various software projects. CVS lets several people
101 work on the same software at the same time, allowing changes to be
102 checked in incrementally. </para>
104 <para>This section is a set of guidelines for how to use our CVS
105 repository, and will probably evolve in time. The main thing to
106 remember is that most mistakes can be undone, but if there's
107 anything you're not sure about feel free to bug the local CVS
108 meister (namely Jeff Lewis
109 <email>jlewis@galois.com</email>). </para>
111 <sect2 id="cvs-access">
112 <title>Getting access to the CVS Repository</title>
114 <para>You can access the repository in one of two ways:
115 read-only (<xref linkend="cvs-read-only"/>), or read-write (<xref
116 linkend="cvs-read-write"/>).</para>
118 <sect3 id="cvs-read-only">
119 <title>Remote Read-only CVS Access</title>
121 <para>Read-only access is available to anyone - there's no
122 need to ask us first. With read-only CVS access you can do
123 anything except commit changes to the repository. You can
124 make changes to your local tree, and still use CVS's merge
125 facility to keep your tree up to date, and you can generate
126 patches using 'cvs diff' in order to send to us for
129 <para>To get read-only access to the repository:</para>
133 <para>Make sure that <application>cvs</application> is
134 installed on your machine.</para>
137 <para>Set your <literal>$CVSROOT</literal> environment variable to
138 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
139 <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
140 have any trailing spaces on that line, otherwise CVS will respond with
141 a perplexing message like
142 <screen>/cvs : no such repository</screen></para>
145 <para>Run the command</para>
146 <screen>$ cvs login</screen>
147 <para>The password is simply <literal>cvs</literal>. This
148 sets up a file in your home directory called
149 <literal>.cvspass</literal>, which squirrels away the
150 dummy password, so you only need to do this step once.</para>
154 <para>Now go to <xref linkend="cvs-first"/>.</para>
159 <sect3 id="cvs-read-write">
160 <title>Remote Read-Write CVS Access</title>
162 <para>We generally supply read-write access to folk doing
163 serious development on some part of the source tree, when
164 going through us would be a pain. If you're developing some
165 feature, or think you have the time and inclination to fix
166 bugs in our sources, feel free to ask for read-write
167 access. There is a certain amount of responsibility that goes
168 with commit privileges; we are more likely to grant you access
169 if you've demonstrated your competence by sending us patches
170 via mail in the past.</para>
172 <para>To get remote read-write CVS access, you need to do the
173 following steps.</para>
177 <para>Make sure that <literal>cvs</literal> and
178 <literal>ssh</literal> are both installed on your
183 <para>Generate a DSA private-key/public-key pair, thus:</para>
184 <screen>$ ssh-keygen -d</screen>
185 <para>(<literal>ssh-keygen</literal> comes with
186 <literal>ssh</literal>.) Running <literal>ssh-keygen
187 -d</literal> creates the private and public keys in
188 <literal>$HOME/.ssh/id_dsa</literal> and
189 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
190 (assuming you accept the standard defaults).</para>
192 <para><literal>ssh-keygen -d</literal> will only work if
193 you have Version 2 <literal>ssh</literal> installed; it
194 will fail harmlessly otherwise. If you only have Version
195 1 you can instead generate an RSA key pair using plain</para>
196 <screen>$ ssh-keygen</screen>
198 <para>Doing so creates the private and public RSA keys in
199 <literal>$HOME/.ssh/identity</literal> and
200 <literal>$HOME/.ssh/identity.pub</literal>
203 <para>[Deprecated.] Incidentally, you can force a Version
204 2 <literal>ssh</literal> to use the Version 1 protocol by
205 creating <literal>$HOME/config</literal> with the
206 following in it:</para>
207 <programlisting>BatchMode Yes
210 Protocol 1</programlisting>
212 <para>In both cases, <literal>ssh-keygen</literal> will
213 ask for a <firstterm>passphrase</firstterm>. The
214 passphrase is a password that protects your private key.
215 In response to the 'Enter passphrase' question, you can
219 <para>[Recommended.] Enter a passphrase, which you
220 will quote each time you use CVS.
221 <literal>ssh-agent</literal> makes this entirely
225 <para>[Deprecated.] Just hit return (i.e. use an empty
226 passphrase); then you won't need to quote the
227 passphrase when using CVS. The downside is that
228 anyone who can see into your <literal>.ssh</literal>
229 directory, and thereby get your private key, can mess
230 up the repository. So you must keep the
231 <literal>.ssh</literal> directory with draconian
232 no-access permissions.</para>
238 <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
245 <para>Send a message to to the CVS repository
246 administrator (currently Jeff Lewis
247 <email>jeff@galois.com</email>), containing:</para>
250 <para>Your desired user-name.</para>
253 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
254 <literal>.ssh/identity.pub</literal>).</para>
257 <para>He will set up your account.</para>
261 <para>Set the following environment variables:</para>
265 <constant>$HOME</constant>: points to your home directory. This is where CVS
266 will look for its <filename>.cvsrc</filename> file.
272 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
274 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
275 <literal>ssh</literal> assumes that your CVS client
276 understands how to execute shell script
277 ("#!"s,really), which is what
278 <literal>ssh</literal> is. This may not be the case on
279 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
280 <literal>ssh1</literal>.</para>
284 <para><literal>$CVSROOT</literal> to
285 <literal>:ext:</literal><replaceable>your-username</replaceable>
286 <literal>@cvs.haskell.org:/home/cvs/root</literal>
287 where <replaceable>your-username</replaceable> is your user name on
288 <literal>cvs.haskell.org</literal>.
290 <para>The <literal>CVSROOT</literal> environment variable will
291 be recorded in the checked-out tree, so you don't need to set
292 this every time. </para>
298 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
299 if you want to use an Emacs buffer for typing in those long commit messages.
305 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
306 set this to point to <filename>bash.exe</filename>.
317 Put the following in <filename>$HOME/.cvsrc</filename>:
320 <programlisting>checkout -P
323 diff -u</programlisting>
326 These are the default options for the specified CVS commands,
327 and represent better defaults than the usual ones. (Feel
328 free to change them.)
332 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
333 the 8.3 DOS filesystem, but that restriction should have
334 been lifted by now (i.e., you're using VFAT or later filesystems.) If
335 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
343 <para>[Experts.] Once your account is set up, you can get
344 access from other machines without bothering Jeff, thus:</para>
347 <para>Generate a public/private key pair on the new
351 <para>Use ssh to log in to
352 <literal>cvs.haskell.org</literal>, from your old
356 <para>Add the public key for the new machine to the file
357 <literal>$HOME/ssh/authorized_keys</literal> on
358 <literal>cvs.haskell.org</literal>.
359 (<literal>authorized_keys2</literal>, I think, for Version
363 <para>Make sure that the new version of
364 <literal>authorized_keys</literal> still has 600 file
373 <sect2 id="cvs-first">
374 <title>Checking Out a Source Tree</title>
378 <para>Make sure you set your <literal>CVSROOT</literal>
379 environment variable according to either of the remote
380 methods above. The Approved Way to check out a source tree
381 is as follows:</para>
383 <screen>$ cvs checkout fpconfig</screen>
385 <para>At this point you have a new directory called
386 <literal>fptools</literal> which contains the basic stuff
387 for the fptools suite, including the configuration files and
388 some other junk. </para>
390 <para>[Windows users.] The following messages appear to be harmless:
391 <screen>setsockopt IPTOS_LOWDELAY: Invalid argument
392 setsockopt IPTOS_THROUGHPUT: Invalid argument</screen>
396 <para>You can call the fptools directory whatever you like,
397 CVS won't mind: </para>
399 <screen>$ mv fptools <replaceable>directory</replaceable></screen>
401 <para> NB: after you've read the CVS manual you might be
402 tempted to try</para>
403 <screen>$ cvs checkout -d <replaceable>directory</replaceable> fpconfig</screen>
405 <para>instead of checking out <literal>fpconfig</literal>
406 and then renaming it. But this doesn't work, and will
407 result in checking out the entire repository instead of just
408 the <literal>fpconfig</literal> bit.</para>
409 <screen>$ cd <replaceable>directory</replaceable>
410 $ cvs checkout ghc hslibs libraries</screen>
412 <para>The second command here checks out the relevant
413 modules you want to work on. For a GHC build, for instance,
414 you need at least the <literal>ghc</literal>,
415 <literal>hslibs</literal> and <literal>libraries</literal>
416 modules (for a full list of the projects available, see
417 <xref linkend="projects"/>).</para>
419 <para>Remember that if you do not have
420 <literal>happy</literal> and/or <literal>Alex</literal>
421 installed, you need to check them out as well.</para>
426 <sect2 id="cvs-committing">
427 <title>Committing Changes</title>
429 <para>This is only if you have read-write access to the
430 repository. For anoncvs users, CVS will issue a "read-only
431 repository" error if you try to commit changes.</para>
435 <para>Build the software, if necessary. Unless you're just
436 working on documentation, you'll probably want to build the
437 software in order to test any changes you make.</para>
441 <para>Make changes. Preferably small ones first.</para>
445 <para>Test them. You can see exactly what changes you've
446 made by using the <literal>cvs diff</literal> command:</para>
447 <screen>$ cvs diff</screen>
448 <para>lists all the changes (using the
449 <literal>diff</literal> command) in and below the current
450 directory. In emacs, <literal>C-c C-v =</literal> runs
451 <literal>cvs diff</literal> on the current buffer and shows
452 you the results.</para>
456 <para>If you changed something in the
457 <literal>fptools/libraries</literal> subdirectories, also run
458 <literal>make html</literal> to check if the documentation can
459 be generated successfully, too.</para>
463 <para>Before checking in a change, you need to update your
467 $ cvs update</screen>
468 <para>This pulls in any changes that other people have made,
469 and merges them with yours. If there are any conflicts, CVS
470 will tell you, and you'll have to resolve them before you
471 can check your changes in. The documentation describes what
472 to do in the event of a conflict.</para>
474 <para>It's not always necessary to do a full cvs update
475 before checking in a change, since CVS will always tell you
476 if you try to check in a file that someone else has changed.
477 However, you should still update at regular intervals to
478 avoid making changes that don't work in conjuction with
479 changes that someone else made. Keeping an eye on what goes
480 by on the mailing list can help here.</para>
484 <para>When you're happy that your change isn't going to
485 break anything, check it in. For a one-file change:</para>
487 <screen>$ cvs commit <replaceable>filename</replaceable></screen>
489 <para>CVS will then pop up an editor for you to enter a
490 "commit message", this is just a short description
491 of what your change does, and will be kept in the history of
494 <para>If you're using emacs, simply load up the file into a
495 buffer and type <literal>C-x C-q</literal>, and emacs will
496 prompt for a commit message and then check in the file for
499 <para>For a multiple-file change, things are a bit
500 trickier. There are several ways to do this, but this is the
501 way I find easiest. First type the commit message into a
502 temporary file. Then either</para>
504 <screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable></screen>
506 <para>or, if nothing else has changed in this part of the
509 <screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable></screen>
511 <para>where <replaceable>directory</replaceable> is a common
512 parent directory for all your changes, and
513 <replaceable>commit-message</replaceable> is the name of the
514 file containing the commit message.</para>
516 <para>Shortly afterwards, you'll get some mail from the
517 relevant mailing list saying which files changed, and giving
518 the commit message. For a multiple-file change, you should
519 still get only <emphasis>one</emphasis> message.</para>
524 <sect2 id="cvs-update">
525 <title>Updating Your Source Tree</title>
527 <para>It can be tempting to cvs update just part of a source
528 tree to bring in some changes that someone else has made, or
529 before committing your own changes. This is NOT RECOMMENDED!
530 Quite often changes in one part of the tree are dependent on
531 changes in another part of the tree (the
532 <literal>mk/*.mk</literal> files are a good example where
533 problems crop up quite often). Having an inconsistent tree is a
534 major cause of headaches. </para>
536 <para>So, to avoid a lot of hassle, follow this recipe for
537 updating your tree:</para>
540 $ cvs update -P 2>&1 | tee log</screen>
542 <para>Look at the log file, and fix any conflicts (denoted by a
543 <quote>C</quote> in the first column). New directories may have
544 appeared in the repository; CVS doesn't check these out by
545 default, so to get new directories you have to explicitly do
546 <screen>$ cvs update -d</screen>
547 in each project subdirectory. Don't do this at the top level,
548 because then <emphasis>all</emphasis> the projects will be
551 <para>If you're using multiple build trees, then for every build
552 tree you have pointing at this source tree, you need to update
553 the links in case any new files have appeared: </para>
555 <screen>$ cd <replaceable>build-tree</replaceable>
556 $ lndir <replaceable>source-tree</replaceable></screen>
558 <para>Some files might have been removed, so you need to remove
559 the links pointing to these non-existent files:</para>
561 <screen>$ find . -xtype l -exec rm '{}' \;</screen>
563 <para>To be <emphasis>really</emphasis> safe, you should do
566 <screen>$ gmake all</screen>
568 <para>from the top-level, to update the dependencies and build
569 any changed files. </para>
572 <sect2 id="cvs-tags">
573 <title>GHC Tag Policy</title>
575 <para>If you want to check out a particular version of GHC,
576 you'll need to know how we tag versions in the repository. The
577 policy (as of 4.04) is:</para>
581 <para>The tree is branched before every major release. The
582 branch tag is <literal>ghc-x-xx-branch</literal>, where
583 <literal>x-xx</literal> is the version number of the release
584 with the <literal>'.'</literal> replaced by a
585 <literal>'-'</literal>. For example, the 4.04 release lives
586 on <literal>ghc-4-04-branch</literal>.</para>
590 <para>The release itself is tagged with
591 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
592 called <literal>ghc-4-06</literal>.</para>
596 <para>We didn't always follow these guidelines, so to see
597 what tags there are for previous versions, do <literal>cvs
598 log</literal> on a file that's been around for a while (like
599 <literal>fptools/ghc/README</literal>).</para>
603 <para>So, to check out a fresh GHC 4.06 tree you would
606 <screen>$ cvs co -r ghc-4-06 fpconfig
608 $ cvs co -r ghc-4-06 ghc hslibs</screen>
611 <sect2 id="cvs-hints">
612 <title>General Hints</title>
616 <para>As a general rule: commit changes in small units,
617 preferably addressing one issue or implementing a single
618 feature. Provide a descriptive log message so that the
619 repository records exactly which changes were required to
620 implement a given feature/fix a bug. I've found this
621 <emphasis>very</emphasis> useful in the past for finding out
622 when a particular bug was introduced: you can just wind back
623 the CVS tree until the bug disappears.</para>
627 <para>Keep the sources at least *buildable* at any given
628 time. No doubt bugs will creep in, but it's quite easy to
629 ensure that any change made at least leaves the tree in a
630 buildable state. We do nightly builds of GHC to keep an eye
631 on what things work/don't work each day and how we're doing
632 in relation to previous verions. This idea is truely wrecked
633 if the compiler won't build in the first place!</para>
637 <para>To check out extra bits into an already-checked-out
638 tree, use the following procedure. Suppose you have a
639 checked-out fptools tree containing just ghc, and you want
640 to add nofib to it:</para>
643 $ cvs checkout nofib</screen>
648 $ cvs update -d nofib</screen>
650 <para>(the -d flag tells update to create a new
651 directory). If you just want part of the nofib suite, you
655 $ cvs checkout nofib/spectral</screen>
657 <para>This works because <literal>nofib</literal> is a
658 module in its own right, and spectral is a subdirectory of
659 the nofib module. The path argument to checkout must always
660 start with a module name. There's no equivalent form of this
661 command using <literal>update</literal>.</para>
667 <sect1 id="projects">
668 <title>What projects are there?</title>
670 <para>The <literal>fptools</literal> suite consists of several
671 <firstterm>projects</firstterm>, most of which can be downloaded,
672 built and installed individually. Each project corresponds to a
673 subdirectory in the source tree, and if checking out from CVS then
674 each project can be checked out individually by sitting in the top
675 level of your source tree and typing <command>cvs checkout
676 <replaceable>project</replaceable></command>.</para>
678 <para>Here is a list of the projects currently available:</para>
683 <literal>alex</literal>
684 <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
688 url="http://www.haskell.org/alex/">Alex</ulink> lexical
689 analyser generator for Haskell.</para>
695 <literal>ghc</literal>
696 <indexterm><primary><literal>ghc</literal></primary>
697 <secondary>project</secondary></indexterm>
700 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
701 Haskell Compiler</ulink> (minus libraries). Absolutely
702 required for building GHC.</para>
708 <literal>glafp-utils</literal>
709 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
712 <para>Utility programs, some of which are used by the
713 build/installation system. Required for pretty much
720 <literal>greencard</literal>
721 <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
725 url="http://www.haskell.org/greencard/">GreenCard</ulink>
726 system for generating Haskell foreign function
733 <literal>haggis</literal>
734 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
738 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
739 Haskell GUI framework.</para>
745 <literal>haddock</literal>
746 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
750 url="http://www.haskell.org/haddock/">Haddock</ulink>
751 documentation tool.</para>
757 <literal>happy</literal>
758 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
762 url="http://www.haskell.org/happy/">Happy</ulink> Parser
769 <literal>hdirect</literal>
770 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
774 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
775 Haskell interoperability tool.</para>
781 <literal>hood</literal>
782 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
785 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
786 Object Observation Debugger</ulink>.</para>
792 <literal>hslibs</literal>
793 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
796 <para>Supplemental libraries for GHC
797 (<emphasis>required</emphasis> for building GHC).</para>
803 <literal>libraries</literal>
804 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
807 <para>Hierarchical Haskell library suite
808 (<emphasis>required</emphasis> for building GHC).</para>
814 <literal>mhms</literal>
815 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
818 <para>The Modular Haskell Metric System.</para>
824 <literal>nofib</literal>
825 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
828 <para>The NoFib suite: A collection of Haskell programs used
829 primarily for benchmarking.</para>
835 <literal>testsuite</literal>
836 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
839 <para>A testing framework, including GHC's regression test
845 <para>So, to build GHC you need at least the
846 <literal>ghc</literal>, <literal>libraries</literal> and
847 <literal>hslibs</literal> projects (a GHC source distribution will
848 already include the bits you need).</para>
851 <sect1 id="sec-build-checks">
852 <title>Things to check before you start</title>
854 <para>Here's a list of things to check before you get
859 <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
860 space needed: from about 100Mb for a basic GHC
861 build, up to probably 500Mb for a GHC build with everything
862 included (libraries built several different ways,
867 <para>Use an appropriate machine / operating system. <xref
868 linkend="sec-port-info"/> lists the supported platforms; if
869 yours isn't amongst these then you can try porting GHC (see
870 <xref linkend="sec-porting-ghc"/>).</para>
874 <para>Be sure that the “pre-supposed” utilities are
875 installed. <xref linkend="sec-pre-supposed"/>
880 <para>If you have any problem when building or installing the
881 Glasgow tools, please check the “known pitfalls” (<xref
882 linkend="sec-build-pitfalls"/>). Also check the FAQ for the
883 version you're building, which is part of the User's Guide and
884 available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
887 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
889 <para>If you feel there is still some shortcoming in our
890 procedure or instructions, please report it.</para>
892 <para>For GHC, please see the <ulink
893 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
894 section of the GHC Users' Guide</ulink>, to maximise the
895 usefulness of your report.</para>
897 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
898 <para>If in doubt, please send a message to
899 <email>glasgow-haskell-bugs@haskell.org</email>.
900 <indexterm><primary>bugs</primary><secondary>mailing
901 list</secondary></indexterm></para>
906 <sect1 id="sec-port-info">
907 <title>What machines the Glasgow tools run on</title>
909 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
910 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
911 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
913 <para>The main question is whether or not the Haskell compiler
914 (GHC) runs on your platform.</para>
916 <para>A “platform” is a
917 architecture/manufacturer/operating-system combination, such as
918 <literal>sparc-sun-solaris2</literal>. Other common ones are
919 <literal>alpha-dec-osf2</literal>,
920 <literal>hppa1.1-hp-hpux9</literal>,
921 <literal>i386-unknown-linux</literal>,
922 <literal>i386-unknown-solaris2</literal>,
923 <literal>i386-unknown-freebsd</literal>,
924 <literal>i386-unknown-cygwin32</literal>,
925 <literal>m68k-sun-sunos4</literal>,
926 <literal>mips-sgi-irix5</literal>,
927 <literal>sparc-sun-sunos4</literal>,
928 <literal>sparc-sun-solaris2</literal>,
929 <literal>powerpc-ibm-aix</literal>.</para>
931 <para>Some libraries may only work on a limited number of
932 platforms; for example, a sockets library is of no use unless the
933 operating system supports the underlying BSDisms.</para>
936 <title>What platforms the Haskell compiler (GHC) runs on</title>
938 <indexterm><primary>fully-supported platforms</primary></indexterm>
939 <indexterm><primary>native-code generator</primary></indexterm>
940 <indexterm><primary>registerised ports</primary></indexterm>
941 <indexterm><primary>unregisterised ports</primary></indexterm>
943 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
944 native-code generator; (b) next best is a
945 “registerised” port; (c) the bare minimum is an
946 “unregisterised” port.
947 (“Unregisterised” is so terrible that we won't say
948 more about it).</para>
950 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
951 FreeBSD and Linux, so those are the best supported platforms,
952 unsurprisingly.</para>
954 <para>Here's everything that's known about GHC ports. We
955 identify platforms by their “canonical”
956 CPU/Manufacturer/OS triple.</para>
960 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
961 <indexterm><primary>alpha-dec-osf</primary></indexterm>
962 <indexterm><primary>alpha-dec-linux</primary></indexterm>
963 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
964 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
965 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
968 <para>The OSF port is currently working (as of GHC version
969 5.02.1) and well supported. The native code generator is
970 currently non-working. Other operating systems will
971 require some minor porting.</para>
976 <term>sparc-sun-sunos4
977 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
980 <para>Probably works with minor tweaks, hasn't been tested
986 <term>sparc-sun-solaris2
987 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
990 <para>Fully supported (at least for Solaris 2.7 and 2.6),
991 including native-code generator.</para>
996 <term>sparc-unknown-openbsd
997 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
1000 <para>Supported, including native-code generator. The
1001 same should also be true of NetBSD</para>
1006 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
1007 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1010 <para>A registerised port is available for version 4.08,
1011 but GHC hasn't been built on that platform since (as far
1012 as we know). No native-code generator.</para>
1017 <term>i386-unknown-linux (PCs running Linux, ELF binary format)
1018 <indexterm><primary>i386-*-linux</primary></indexterm>
1021 <para>GHC works registerised and has a native code
1022 generator. You <emphasis>must</emphasis> have GCC 2.7.x
1023 or later. NOTE about <literal>glibc</literal> versions:
1024 GHC binaries built on a system running <literal>glibc
1025 2.0</literal> won't work on a system running
1026 <literal>glibc 2.1</literal>, and vice versa. In general,
1027 don't expect compatibility between
1028 <literal>glibc</literal> versions, even if the shared
1029 library version hasn't changed.</para>
1034 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
1035 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1038 <para>GHC works registerised. Pre-built packages are
1039 available in the native package format, so if you just
1040 need binaries you're better off just installing the
1041 package (it might even be on your installation
1047 <term>i386-unknown-openbsd (PCs running OpenBSD)
1048 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1051 <para>Supported, with native code generator. Packages are
1052 available through the ports system in the native package
1058 <term>i386-unknown-netbsd (PCs running NetBSD)
1059 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1062 <para>Will require some minor porting effort, but should
1063 work registerised.</para>
1068 <term>i386-unknown-mingw32 (PCs running Windows)
1069 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1072 <para>Fully supported under Win9x, WinNT, Win2k, and
1073 WinXP. Includes a native code generator. Building from
1074 source requires a recent <ulink
1075 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1076 to be installed.</para>
1081 <term>ia64-unknown-linux
1082 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1085 <para>Supported, except there is no native code
1091 <term>x86_64-unknown-linux
1092 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1095 <para>GHC currently works unregisterised. A registerised
1096 port is in progress.</para>
1101 <term>amd64-unknown-openbsd
1102 <indexterm><primary>amd64-unknown-linux</primary></indexterm>
1105 <para>(This is the same as x86_64-unknown-openbsd). GHC
1106 currently works unregisterised. A registerised port is in
1112 <term>mips-sgi-irix5
1113 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1116 <para>Port has worked in the past, but hasn't been tested
1117 for some time (and will certainly have rotted in various
1118 ways). As usual, we don't have access to machines and
1119 there hasn't been an overwhelming demand for this port,
1120 but feel free to get in touch.</para>
1125 <term>mips64-sgi-irix6
1126 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
1129 <para>GHC currently works unregisterised.</para>
1134 <term>powerpc-ibm-aix
1135 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1138 <para>Port currently doesn't work, needs some minimal
1139 porting effort. As usual, we don't have access to
1140 machines and there hasn't been an overwhelming demand for
1141 this port, but feel free to get in touch.</para>
1146 <term>powerpc-apple-darwin
1147 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1150 <para>Supported registerised. Native code generator is
1151 almost working.</para>
1156 <term>powerpc-apple-linux
1157 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1160 <para>Not supported (yet).</para>
1165 <para>Various other systems have had GHC ported to them in the
1166 distant past, including various Motorola 68k boxes. The 68k
1167 support still remains, but porting to one of these systems will
1168 certainly be a non-trivial task.</para>
1172 <title>What machines the other tools run on</title>
1174 <para>Unless you hear otherwise, the other tools work if GHC
1180 <sect1 id="sec-pre-supposed">
1181 <title>Installing pre-supposed utilities</title>
1183 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1184 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1186 <para>Here are the gory details about some utility programs you
1187 may need; <command>perl</command>, <command>gcc</command> and
1188 <command>happy</command> are the only important
1189 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1190 important if you're going for Parallel Haskell.) The
1191 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1192 script will tell you if you are missing something.</para>
1198 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1199 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1202 <para>GHC is required to build many of the tools, including
1203 GHC itself. If you need to port GHC to your platform
1204 because there isn't a binary distribution of GHC available,
1205 then see <xref linkend="sec-porting-ghc"/>.</para>
1207 <para>Which version of GHC you need will depend on the
1208 packages you intend to build. GHC itself will normally
1209 build using one of several older versions of itself - check
1210 the announcement or release notes for details.</para>
1216 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1217 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1220 <para><emphasis>You have to have Perl to proceed!</emphasis>
1221 Perl version 5 at least is required. GHC has been known to
1222 tickle bugs in Perl, so if you find that Perl crashes when
1223 running GHC try updating (or downgrading) your Perl
1224 installation. Versions of Perl that we use and are known to
1225 be fairly stable are 5.005 and 5.6.1.</para>
1227 <para>For Win32 platforms, you should use the binary
1228 supplied in the InstallShield (copy it to
1229 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1232 <para>Perl should be put somewhere so that it can be invoked
1233 by the <literal>#!</literal> script-invoking
1234 mechanism. The full pathname may need to be less than 32
1235 characters long on some systems.</para>
1240 <term>GNU C (<command>gcc</command>)
1241 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
1242 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
1245 <para>We recommend using GCC version 2.95.2 on all
1246 platforms. Failing that, version 2.7.2 is stable on most
1247 platforms. Earlier versions of GCC can be assumed not to
1248 work, and versions in between 2.7.2 and 2.95.2 (including
1249 <command>egcs</command>) have varying degrees of stability
1250 depending on the platform.</para>
1252 <para>GCC 3.2 is currently known to have problems building
1253 GHC on Sparc, but is stable on x86.</para>
1255 <para>If your GCC dies with “internal error” on
1256 some GHC source file, please let us know, so we can report
1257 it and get things improved. (Exception: on x86
1258 boxes—you may need to fiddle with GHC's
1259 <option>-monly-N-regs</option> option; see the User's
1266 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
1269 <para>The fptools build system makes heavy use of features
1270 specific to GNU <command>make</command>, so you must have
1271 this installed in order to build any of the fptools
1278 <indexterm><primary>Happy</primary></indexterm>
1281 <para>Happy is a parser generator tool for Haskell, and is
1282 used to generate GHC's parsers. Happy is written in
1283 Haskell, and is a project in the CVS repository
1284 (<literal>fptools/happy</literal>). It can be built from
1285 source, but bear in mind that you'll need GHC installed in
1286 order to build it. To avoid the chicken/egg problem,
1287 install a binary distribution of either Happy or GHC to get
1288 started. Happy distributions are available from <ulink
1289 url="http://www.haskell.org/happy/">Happy's Web
1290 Page</ulink>.</para>
1296 <indexterm><primary>Alex</primary></indexterm>
1299 <para>Alex is a lexical-analyser generator for Haskell,
1300 which GHC uses to generate its lexer. Like Happy, Alex is
1301 written in Haskell and is a project in the CVS repository.
1302 Alex distributions are available from <ulink
1303 url="http://www.haskell.org/alex/">Alex's Web
1304 Page</ulink>.</para>
1310 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
1311 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
1314 <para>GNU autoconf is needed if you intend to build from the
1315 CVS sources, it is <emphasis>not</emphasis> needed if you
1316 just intend to build a standard source distribution.</para>
1318 <para>Version 2.52 or later of the autoconf package is required.
1319 NB. version 2.13 will no longer work, as of GHC version
1322 <para><command>autoreconf</command> (from the autoconf package)
1323 recursively builds <command>configure</command> scripts from
1324 the corresponding <filename>configure.ac</filename> and
1325 <filename>aclocal.m4</filename> files. If you modify one of
1326 the latter files, you'll need <command>autoreconf</command> to
1327 rebuild the corresponding <filename>configure</filename>.</para>
1332 <term><command>sed</command>
1333 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1334 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1337 <para>You need a working <command>sed</command> if you are
1338 going to build from sources. The build-configuration stuff
1339 needs it. GNU sed version 2.0.4 is no good! It has a bug
1340 in it that is tickled by the build-configuration. 2.0.5 is
1341 OK. Others are probably OK too (assuming we don't create too
1342 elaborate configure scripts.)</para>
1347 <para>One <literal>fptools</literal> project is worth a quick note
1348 at this point, because it is useful for all the others:
1349 <literal>glafp-utils</literal> contains several utilities which
1350 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1351 Like <command>lndir</command> for creating symbolic link
1354 <sect2 id="pre-supposed-gph-tools">
1355 <title>Tools for building parallel GHC (GPH)</title>
1359 <term>PVM version 3:
1360 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1361 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1364 <para>PVM is the Parallel Virtual Machine on which
1365 Parallel Haskell programs run. (You only need this if you
1366 plan to run Parallel Haskell. Concurrent Haskell, which
1367 runs concurrent threads on a uniprocessor doesn't need
1368 it.) Underneath PVM, you can have (for example) a network
1369 of workstations (slow) or a multiprocessor box
1372 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1373 It is readily available on the net; I think I got it from
1374 <literal>research.att.com</literal>, in
1375 <filename>netlib</filename>.</para>
1377 <para>A PVM installation is slightly quirky, but easy to
1378 do. Just follow the <filename>Readme</filename>
1379 instructions.</para>
1384 <term><command>bash</command>:
1385 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1388 <para>Sadly, the <command>gr2ps</command> script, used to
1389 convert “parallelism profiles” to PostScript,
1390 is written in Bash (GNU's Bourne Again shell). This bug
1391 will be fixed (someday).</para>
1397 <sect2 id="pre-supposed-other-tools">
1398 <title>Other useful tools</title>
1403 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1404 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1407 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1408 to build a couple of utilities in
1409 <literal>glafp-utils</literal>. Depending on your
1410 operating system, the supplied <command>lex</command> may
1411 or may not work; you should get the GNU version.</para>
1416 <para>More tools are required if you want to format the documentation
1417 that comes with GHC and other fptools projects. See <xref
1418 linkend="building-docs"/>.</para>
1422 <sect1 id="sec-building-from-source">
1423 <title>Building from source</title>
1425 <indexterm><primary>Building from source</primary></indexterm>
1426 <indexterm><primary>Source, building from</primary></indexterm>
1428 <para>You've been rash enough to want to build some of the Glasgow
1429 Functional Programming tools (GHC, Happy, nofib, etc.) from
1430 source. You've slurped the source, from the CVS repository or
1431 from a source distribution, and now you're sitting looking at a
1432 huge mound of bits, wondering what to do next.</para>
1434 <para>Gingerly, you type <command>make</command>. Wrong
1437 <para>This rest of this guide is intended for duffers like me, who
1438 aren't really interested in Makefiles and systems configurations,
1439 but who need a mental model of the interlocking pieces so that
1440 they can make them work, extend them consistently when adding new
1441 software, and lay hands on them gently when they don't
1444 <sect2 id="quick-start">
1445 <title>Quick Start</title>
1447 <para>If you are starting from a source distribution, and just
1448 want a completely standard build, then the following procedure should
1449 work (unless you're on Windows, in which case go to <xref linkend="winbuild" />).</para>
1451 <screen>$ autoreconf
1454 $ make install</screen>
1456 <para>For GHC, this will do a 2-stage bootstrap build of the
1457 compiler, with profiling libraries, and install the
1460 <para>If you want to do anything at all non-standard, or you
1461 want to do some development, read on...</para>
1464 <sect2 id="sec-source-tree">
1465 <title>Your source tree</title>
1467 <para>The source code is held in your <emphasis>source
1468 tree</emphasis>. The root directory of your source tree
1469 <emphasis>must</emphasis> contain the following directories and
1474 <para><filename>Makefile</filename>: the root
1479 <para><filename>mk/</filename>: the directory that contains
1480 the main Makefile code, shared by all the
1481 <literal>fptools</literal> software.</para>
1485 <para><filename>configure.ac</filename>,
1486 <filename>config.sub</filename>,
1487 <filename>config.guess</filename>: these files support the
1488 configuration process.</para>
1492 <para><filename>install-sh</filename>.</para>
1496 <para>All the other directories are individual
1497 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1498 system—for example, the Glasgow Haskell Compiler
1499 (<literal>ghc</literal>), the Happy parser generator
1500 (<literal>happy</literal>), the <literal>nofib</literal>
1501 benchmark suite, and so on. You can have zero or more of these.
1502 Needless to say, some of them are needed to build others.</para>
1504 <para>The important thing to remember is that even if you want
1505 only one project (<literal>happy</literal>, say), you must have
1506 a source tree whose root directory contains
1507 <filename>Makefile</filename>, <filename>mk/</filename>,
1508 <filename>configure.ac</filename>, and the project(s) you want
1509 (<filename>happy/</filename> in this case). You cannot get by
1510 with just the <filename>happy/</filename> directory.</para>
1514 <title>Build trees</title>
1515 <indexterm><primary>build trees</primary></indexterm>
1516 <indexterm><primary>link trees, for building</primary></indexterm>
1518 <para>If you just want to build the software once on a single
1519 platform, then your source tree can also be your build tree, and
1520 you can skip the rest of this section.</para>
1522 <para>We often want to build multiple versions of our software
1523 for different architectures, or with different options
1524 (e.g. profiling). It's very desirable to share a single copy of
1525 the source code among all these builds.</para>
1527 <para>So for every source tree we have zero or more
1528 <emphasis>build trees</emphasis>. Each build tree is initially
1529 an exact copy of the source tree, except that each file is a
1530 symbolic link to the source file, rather than being a copy of
1531 the source file. There are “standard” Unix
1532 utilities that make such copies, so standard that they go by
1534 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1535 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1536 are two (If you don't have either, the source distribution
1537 includes sources for the X11
1538 <command>lndir</command>—check out
1539 <filename>fptools/glafp-utils/lndir</filename>). See <xref
1540 linkend="sec-storysofar"/> for a typical invocation.</para>
1542 <para>The build tree does not need to be anywhere near the
1543 source tree in the file system. Indeed, one advantage of
1544 separating the build tree from the source is that the build tree
1545 can be placed in a non-backed-up partition, saving your systems
1546 support people from backing up untold megabytes of
1547 easily-regenerated, and rapidly-changing, gubbins. The golden
1548 rule is that (with a single exception—<xref
1549 linkend="sec-build-config"/>) <emphasis>absolutely everything in
1550 the build tree is either a symbolic link to the source tree, or
1551 else is mechanically generated</emphasis>. It should be
1552 perfectly OK for your build tree to vanish overnight; an hour or
1553 two compiling and you're on the road again.</para>
1555 <para>You need to be a bit careful, though, that any new files
1556 you create (if you do any development work) are in the source
1557 tree, not a build tree!</para>
1559 <para>Remember, that the source files in the build tree are
1560 <emphasis>symbolic links</emphasis> to the files in the source
1561 tree. (The build tree soon accumulates lots of built files like
1562 <filename>Foo.o</filename>, as well.) You can
1563 <emphasis>delete</emphasis> a source file from the build tree
1564 without affecting the source tree (though it's an odd thing to
1565 do). On the other hand, if you <emphasis>edit</emphasis> a
1566 source file from the build tree, you'll edit the source-tree
1567 file directly. (You can set up Emacs so that if you edit a
1568 source file from the build tree, Emacs will silently create an
1569 edited copy of the source file in the build tree, leaving the
1570 source file unchanged; but the danger is that you think you've
1571 edited the source file whereas actually all you've done is edit
1572 the build-tree copy. More commonly you do want to edit the
1573 source file.)</para>
1575 <para>Like the source tree, the top level of your build tree
1576 must be (a linked copy of) the root directory of the
1577 <literal>fptools</literal> suite. Inside Makefiles, the root of
1578 your build tree is called
1579 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1580 In the rest of this document path names are relative to
1581 <constant>$(FPTOOLS_TOP)</constant> unless
1582 otherwise stated. For example, the file
1583 <filename>ghc/mk/target.mk</filename> is actually
1584 <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
1587 <sect2 id="sec-build-config">
1588 <title>Getting the build you want</title>
1590 <para>When you build <literal>fptools</literal> you will be
1591 compiling code on a particular <emphasis>host
1592 platform</emphasis>, to run on a particular <emphasis>target
1593 platform</emphasis> (usually the same as the host
1594 platform)<indexterm><primary>platform</primary></indexterm>.
1595 The difficulty is that there are minor differences between
1596 different platforms; minor, but enough that the code needs to be
1597 a bit different for each. There are some big differences too:
1598 for a different architecture we need to build GHC with a
1599 different native-code generator.</para>
1601 <para>There are also knobs you can turn to control how the
1602 <literal>fptools</literal> software is built. For example, you
1603 might want to build GHC optimised (so that it runs fast) or
1604 unoptimised (so that you can compile it fast after you've
1605 modified it. Or, you might want to compile it with debugging on
1606 (so that extra consistency-checking code gets included) or off.
1609 <para>All of this stuff is called the
1610 <emphasis>configuration</emphasis> of your build. You set the
1611 configuration using a three-step process.</para>
1615 <term>Step 1: get ready for configuration.</term>
1617 <para>NOTE: if you're starting from a source distribution,
1618 rather than CVS sources, you can skip this step.</para>
1620 <para>Change directory to
1621 <constant>$(FPTOOLS_TOP)</constant> and
1622 issue the command</para>
1623 <screen>$ autoreconf</screen>
1624 <indexterm><primary>autoreconf</primary></indexterm>
1625 <para>(with no arguments). This GNU program (recursively) converts
1626 <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
1627 <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
1628 to a shell script called
1629 <filename>$(FPTOOLS_TOP)/configure</filename>.
1630 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
1631 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
1632 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
1633 a message like "No rule to make target 'mk/config.h.in'".
1636 <para>Some projects, including GHC, have their own configure script.
1637 <command>autoreconf</command> takes care of that, too, so all you have
1638 to do is calling <command>autoreconf</command> in the top-level directory
1639 <filename>$(FPTOOLS_TOP)</filename>.</para>
1641 <para>These steps are completely platform-independent; they just mean
1642 that the human-written files (<filename>configure.ac</filename> and
1643 <filename>aclocal.m4</filename>) can be short, although the resulting
1644 files (the <command>configure</command> shell scripts and the C header
1645 template <filename>mk/config.h.in</filename>) are long.</para>
1650 <term>Step 2: system configuration.</term>
1652 <para>Runs the newly-created <command>configure</command>
1653 script, thus:</para>
1655 <screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
1657 <para><command>configure</command>'s mission is to scurry
1658 round your computer working out what architecture it has,
1659 what operating system, whether it has the
1660 <function>vfork</function> system call, where
1661 <command>tar</command> is kept, whether
1662 <command>gcc</command> is available, where various obscure
1663 <literal>#include</literal> files are, whether it's a
1664 leap year, and what the systems manager had for lunch. It
1665 communicates these snippets of information in two
1672 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1674 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1675 substituting for things between
1676 “<literal>@</literal>” brackets. So,
1677 “<literal>@HaveGcc@</literal>” will be
1678 replaced by “<literal>YES</literal>” or
1679 “<literal>NO</literal>” depending on what
1680 <command>configure</command> finds.
1681 <filename>mk/config.mk</filename> is included by every
1682 Makefile (directly or indirectly), so the
1683 configuration information is thereby communicated to
1684 all Makefiles.</para>
1688 <para> It translates
1689 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1691 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1692 The latter is <literal>#include</literal>d by
1693 various C programs, which can thereby make use of
1694 configuration information.</para>
1698 <para><command>configure</command> takes some optional
1699 arguments. Use <literal>./configure --help</literal> to
1700 get a list of the available arguments. Here are some of
1701 the ones you might need:</para>
1705 <term><literal>--with-ghc=<parameter>path</parameter></literal>
1706 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
1709 <para>Specifies the path to an installed GHC which
1710 you would like to use. This compiler will be used
1711 for compiling GHC-specific code (eg. GHC itself).
1712 This option <emphasis>cannot</emphasis> be specified
1713 using <filename>build.mk</filename> (see later),
1714 because <command>configure</command> needs to
1715 auto-detect the version of GHC you're using. The
1716 default is to look for a compiler named
1717 <literal>ghc</literal> in your path.</para>
1722 <term><literal>--with-hc=<parameter>path</parameter></literal>
1723 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
1726 <para>Specifies the path to any installed Haskell
1727 compiler. This compiler will be used for compiling
1728 generic Haskell code. The default is to use
1729 <literal>ghc</literal>.</para>
1734 <term><literal>--with-gcc=<parameter>path</parameter></literal>
1735 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
1738 <para>Specifies the path to the installed GCC. This
1739 compiler will be used to compile all C files,
1740 <emphasis>except</emphasis> any generated by the
1741 installed Haskell compiler, which will have its own
1742 idea of which C compiler (if any) to use. The
1743 default is to use <literal>gcc</literal>.</para>
1751 <term>Step 3: build configuration.</term>
1753 <para>Next, you say how this build of
1754 <literal>fptools</literal> is to differ from the standard
1755 defaults by creating a new file
1756 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1757 <emphasis>in the build tree</emphasis>. This file is the
1758 one and only file you edit in the build tree, precisely
1759 because it says how this build differs from the source.
1760 (Just in case your build tree does die, you might want to
1761 keep a private directory of <filename>build.mk</filename>
1762 files, and use a symbolic link in each build tree to point
1763 to the appropriate one.) So
1764 <filename>mk/build.mk</filename> never exists in the
1765 source tree—you create one in each build tree from
1766 the template. We'll discuss what to put in it
1772 <para>And that's it for configuration. Simple, eh?</para>
1774 <para>What do you put in your build-specific configuration file
1775 <filename>mk/build.mk</filename>? <emphasis>For almost all
1776 purposes all you will do is put make variable definitions that
1777 override those in</emphasis>
1778 <filename>mk/config.mk.in</filename>. The whole point of
1779 <filename>mk/config.mk.in</filename>—and its derived
1780 counterpart <filename>mk/config.mk</filename>—is to define
1781 the build configuration. It is heavily commented, as you will
1782 see if you look at it. So generally, what you do is look at
1783 <filename>mk/config.mk.in</filename>, and add definitions in
1784 <filename>mk/build.mk</filename> that override any of the
1785 <filename>config.mk</filename> definitions that you want to
1786 change. (The override occurs because the main boilerplate file,
1787 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1788 includes <filename>build.mk</filename> after
1789 <filename>config.mk</filename>.)</para>
1791 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1792 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1794 <para>For example, <filename>config.mk.in</filename> contains
1795 the definition:</para>
1797 <programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
1799 <para>The accompanying comment explains that this is the list of
1800 flags passed to GHC when building GHC itself. For doing
1801 development, it is wise to add <literal>-DDEBUG</literal>, to
1802 enable debugging code. So you would add the following to
1803 <filename>build.mk</filename>:</para>
1805 <para>or, if you prefer,</para>
1807 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
1809 <para>GNU <command>make</command> allows existing definitions to
1810 have new text appended using the “<literal>+=</literal>”
1811 operator, which is quite a convenient feature.)</para>
1813 <para>If you want to remove the <literal>-O</literal> as well (a
1814 good idea when developing, because the turn-around cycle gets a
1815 lot quicker), you can just override
1816 <literal>GhcLibHcOpts</literal> altogether:</para>
1818 <programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
1820 <para>When reading <filename>config.mk.in</filename>, remember
1821 that anything between “@...@” signs is going to be substituted
1822 by <command>configure</command> later. You
1823 <emphasis>can</emphasis> override the resulting definition if
1824 you want, but you need to be a bit surer what you are doing.
1825 For example, there's a line that says:</para>
1827 <programlisting>TAR = @TarCmd@</programlisting>
1829 <para>This defines the Make variables <constant>TAR</constant>
1830 to the pathname for a <command>tar</command> that
1831 <command>configure</command> finds somewhere. If you have your
1832 own pet <command>tar</command> you want to use instead, that's
1833 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1835 <programlisting>TAR = mytar</programlisting>
1837 <para>You do not <emphasis>have</emphasis> to have a
1838 <filename>mk/build.mk</filename> file at all; if you don't,
1839 you'll get all the default settings from
1840 <filename>mk/config.mk.in</filename>.</para>
1842 <para>You can also use <filename>build.mk</filename> to override
1843 anything that <command>configure</command> got wrong. One place
1844 where this happens often is with the definition of
1845 <constant>FPTOOLS_TOP_ABS</constant>: this
1846 variable is supposed to be the canonical path to the top of your
1847 source tree, but if your system uses an automounter then the
1848 correct directory is hard to find automatically. If you find
1849 that <command>configure</command> has got it wrong, just put the
1850 correct definition in <filename>build.mk</filename>.</para>
1854 <sect2 id="sec-storysofar">
1855 <title>The story so far</title>
1857 <para>Let's summarise the steps you need to carry to get
1858 yourself a fully-configured build tree from scratch.</para>
1862 <para> Get your source tree from somewhere (CVS repository
1863 or source distribution). Say you call the root directory
1864 <filename>myfptools</filename> (it does not have to be
1865 called <filename>fptools</filename>). Make sure that you
1866 have the essential files (see <xref
1867 linkend="sec-source-tree"/>).</para>
1872 <para>(Optional) Use <command>lndir</command> or
1873 <command>mkshadowdir</command> to create a build tree.</para>
1875 <screen>$ cd myfptools
1876 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
1878 <para>(N.B. <command>mkshadowdir</command>'s first argument
1879 is taken relative to its second.) You probably want to give
1880 the build tree a name that suggests its main defining
1881 characteristic (in your mind at least), in case you later
1886 <para>Change directory to the build tree. Everything is
1887 going to happen there now.</para>
1889 <screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
1894 <para>Prepare for system configuration:</para>
1896 <screen>$ autoreconf</screen>
1898 <para>(You can skip this step if you are starting from a
1899 source distribution, and you already have
1900 <filename>configure</filename> and
1901 <filename>mk/config.h.in</filename>.)</para>
1905 <para>Do system configuration:</para>
1907 <screen>$ ./configure</screen>
1909 <para>Don't forget to check whether you need to add any
1910 arguments to <literal>configure</literal>; for example, a
1911 common requirement is to specify which GHC to use with
1912 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1916 <para>Create the file <filename>mk/build.mk</filename>,
1917 adding definitions for your desired configuration
1920 <screen>$ emacs mk/build.mk</screen>
1924 <para>You can make subsequent changes to
1925 <filename>mk/build.mk</filename> as often as you like. You do
1926 not have to run any further configuration programs to make these
1927 changes take effect. In theory you should, however, say
1928 <command>gmake clean</command>, <command>gmake all</command>,
1929 because configuration option changes could affect
1930 anything—but in practice you are likely to know what's
1935 <title>Making things</title>
1937 <para>At this point you have made yourself a fully-configured
1938 build tree, so you are ready to start building real
1941 <para>The first thing you need to know is that <emphasis>you
1942 must use GNU <command>make</command>, usually called
1943 <command>gmake</command>, not standard Unix
1944 <command>make</command></emphasis>. If you use standard Unix
1945 <command>make</command> you will get all sorts of error messages
1946 (but no damage) because the <literal>fptools</literal>
1947 <command>Makefiles</command> use GNU <command>make</command>'s
1948 facilities extensively.</para>
1950 <para>To just build the whole thing, <command>cd</command> to
1951 the top of your <literal>fptools</literal> tree and type
1952 <command>gmake</command>. This will prepare the tree and build
1953 the various projects in the correct order.</para>
1956 <sect2 id="sec-bootstrapping">
1957 <title>Bootstrapping GHC</title>
1959 <para>GHC requires a 2-stage bootstrap in order to provide
1960 full functionality, including GHCi. By a 2-stage bootstrap, we
1961 mean that the compiler is built once using the installed GHC,
1962 and then again using the compiler built in the first stage. You
1963 can also build a stage 3 compiler, but this normally isn't
1964 necessary except to verify that the stage 2 compiler is working
1967 <para>Note that when doing a bootstrap, the stage 1 compiler
1968 must be built, followed by the runtime system and libraries, and
1969 then the stage 2 compiler. The correct ordering is implemented
1970 by the top-level fptools <filename>Makefile</filename>, so if
1971 you want everything to work automatically it's best to start
1972 <command>make</command> from the top of the tree. When building
1973 GHC, the top-level fptools <filename>Makefile</filename> is set
1974 up to do a 2-stage bootstrap by default (when you say
1975 <command>make</command>). Some other targets it supports
1982 <para>Build everything as normal, including the stage 1
1990 <para>Build the stage 2 compiler only.</para>
1997 <para>Build the stage 3 compiler only.</para>
2002 <term>bootstrap</term> <term>bootstrap2</term>
2004 <para>Build stage 1 followed by stage 2.</para>
2009 <term>bootstrap3</term>
2011 <para>Build stages 1, 2 and 3.</para>
2016 <term>install</term>
2018 <para>Install everything, including the compiler built in
2019 stage 2. To override the stage, say <literal>make install
2020 stage=<replaceable>n</replaceable></literal> where
2021 <replaceable>n</replaceable> is the stage to install.</para>
2026 <para>The top-level <filename>Makefile</filename> also arranges
2027 to do the appropriate <literal>make boot</literal> steps (see
2028 below) before actually building anything.</para>
2030 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2031 and <literal>stage3</literal> targets also work in the
2032 <literal>ghc/compiler</literal> directory, but don't forget that
2033 each stage requires its own <literal>make boot</literal> step:
2034 for example, you must do</para>
2036 <screen>$ make boot stage=2</screen>
2038 <para>before <literal>make stage2</literal> in
2039 <literal>ghc/compiler</literal>.</para>
2042 <sect2 id="sec-standard-targets">
2043 <title>Standard Targets</title>
2044 <indexterm><primary>targets, standard makefile</primary></indexterm>
2045 <indexterm><primary>makefile targets</primary></indexterm>
2047 <para>In any directory you should be able to make the following:</para>
2051 <term><literal>boot</literal></term>
2053 <para>does the one-off preparation required to get ready
2054 for the real work. Notably, it does <command>gmake
2055 depend</command> in all directories that contain programs.
2056 It also builds the necessary tools for compilation to
2059 <para>Invoking the <literal>boot</literal> target
2060 explicitly is not normally necessary. From the top-level
2061 <literal>fptools</literal> directory, invoking
2062 <literal>gmake</literal> causes <literal>gmake boot
2063 all</literal> to be invoked in each of the project
2064 subdirectories, in the order specified by
2065 <literal>$(AllTargets)</literal> in
2066 <literal>config.mk</literal>.</para>
2068 <para>If you're working in a subdirectory somewhere and
2069 need to update the dependencies, <literal>gmake
2070 boot</literal> is a good way to do it.</para>
2075 <term><literal>all</literal></term>
2077 <para>makes all the final target(s) for this Makefile.
2078 Depending on which directory you are in a “final
2079 target” may be an executable program, a library
2080 archive, a shell script, or a Postscript file. Typing
2081 <command>gmake</command> alone is generally the same as
2082 typing <command>gmake all</command>.</para>
2087 <term><literal>install</literal></term>
2089 <para>installs the things built by <literal>all</literal>
2090 (except for the documentation). Where does it install
2091 them? That is specified by
2092 <filename>mk/config.mk.in</filename>; you can override it
2093 in <filename>mk/build.mk</filename>, or by running
2094 <command>configure</command> with command-line arguments
2095 like <literal>--bindir=/home/simonpj/bin</literal>; see
2096 <literal>./configure --help</literal> for the full
2102 <term><literal>install-docs</literal></term>
2104 <para>installs the documentation. Otherwise behaves just
2105 like <literal>install</literal>.</para>
2110 <term><literal>uninstall</literal></term>
2112 <para>reverses the effect of
2113 <literal>install</literal>.</para>
2118 <term><literal>clean</literal></term>
2120 <para>Delete all files from the current directory that are
2121 normally created by building the program. Don't delete
2122 the files that record the configuration, or files
2123 generated by <command>gmake boot</command>. Also preserve
2124 files that could be made by building, but normally aren't
2125 because the distribution comes with them.</para>
2130 <term><literal>distclean</literal></term>
2132 <para>Delete all files from the current directory that are
2133 created by configuring or building the program. If you
2134 have unpacked the source and built the program without
2135 creating any other files, <literal>make
2136 distclean</literal> should leave only the files that were
2137 in the distribution.</para>
2142 <term><literal>mostlyclean</literal></term>
2144 <para>Like <literal>clean</literal>, but may refrain from
2145 deleting a few files that people normally don't want to
2151 <term><literal>maintainer-clean</literal></term>
2153 <para>Delete everything from the current directory that
2154 can be reconstructed with this Makefile. This typically
2155 includes everything deleted by
2156 <literal>distclean</literal>, plus more: C source files
2157 produced by Bison, tags tables, Info files, and so
2160 <para>One exception, however: <literal>make
2161 maintainer-clean</literal> should not delete
2162 <filename>configure</filename> even if
2163 <filename>configure</filename> can be remade using a rule
2164 in the <filename>Makefile</filename>. More generally,
2165 <literal>make maintainer-clean</literal> should not delete
2166 anything that needs to exist in order to run
2167 <filename>configure</filename> and then begin to build the
2173 <term><literal>check</literal></term>
2175 <para>run the test suite.</para>
2180 <para>All of these standard targets automatically recurse into
2181 sub-directories. Certain other standard targets do not:</para>
2185 <term><literal>configure</literal></term>
2187 <para>is only available in the root directory
2188 <constant>$(FPTOOLS_TOP)</constant>; it has
2189 been discussed in <xref
2190 linkend="sec-build-config"/>.</para>
2195 <term><literal>depend</literal></term>
2197 <para>make a <filename>.depend</filename> file in each
2198 directory that needs it. This <filename>.depend</filename>
2199 file contains mechanically-generated dependency
2200 information; for example, suppose a directory contains a
2201 Haskell source module <filename>Foo.lhs</filename> which
2202 imports another module <literal>Baz</literal>. Then the
2203 generated <filename>.depend</filename> file will contain
2204 the dependency:</para>
2206 <programlisting>Foo.o : Baz.hi</programlisting>
2208 <para>which says that the object file
2209 <filename>Foo.o</filename> depends on the interface file
2210 <filename>Baz.hi</filename> generated by compiling module
2211 <literal>Baz</literal>. The <filename>.depend</filename>
2212 file is automatically included by every Makefile.</para>
2217 <term><literal>binary-dist</literal></term>
2219 <para>make a binary distribution. This is the target we
2220 use to build the binary distributions of GHC and
2226 <term><literal>dist</literal></term>
2228 <para>make a source distribution. Note that this target
2229 does “make distclean” as part of its work;
2230 don't use it if you want to keep what you've built.</para>
2235 <para>Most <filename>Makefile</filename>s have targets other
2236 than these. You can discover them by looking in the
2237 <filename>Makefile</filename> itself.</para>
2241 <title>Using a project from the build tree</title>
2243 <para>If you want to build GHC (say) and just use it direct from
2244 the build tree without doing <literal>make install</literal>
2245 first, you can run the in-place driver script:
2246 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2248 <para> Do <emphasis>NOT</emphasis> use
2249 <filename>ghc/compiler/ghc</filename>, or
2250 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2251 scripts intended for installation, and contain hard-wired paths
2252 to the installed libraries, rather than the libraries in the
2255 <para>Happy can similarly be run from the build tree, using
2256 <filename>happy/src/happy-inplace</filename>, and similarly for
2257 Alex and Haddock.</para>
2261 <title>Fast Making</title>
2263 <indexterm><primary>fastmake</primary></indexterm>
2264 <indexterm><primary>dependencies, omitting</primary></indexterm>
2265 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2267 <para>Sometimes the dependencies get in the way: if you've made
2268 a small change to one file, and you're absolutely sure that it
2269 won't affect anything else, but you know that
2270 <command>make</command> is going to rebuild everything anyway,
2271 the following hack may be useful:</para>
2273 <screen>$ gmake FAST=YES</screen>
2275 <para>This tells the make system to ignore dependencies and just
2276 build what you tell it to. In other words, it's equivalent to
2277 temporarily removing the <filename>.depend</filename> file in
2278 the current directory (where <command>mkdependHS</command> and
2279 friends store their dependency information).</para>
2281 <para>A bit of history: GHC used to come with a
2282 <command>fastmake</command> script that did the above job, but
2283 GNU make provides the features we need to do it without
2284 resorting to a script. Also, we've found that fastmaking is
2285 less useful since the advent of GHC's recompilation checker (see
2286 the User's Guide section on "Separate Compilation").</para>
2290 <sect1 id="sec-makefile-arch">
2291 <title>The <filename>Makefile</filename> architecture</title>
2292 <indexterm><primary>makefile architecture</primary></indexterm>
2294 <para><command>make</command> is great if everything
2295 works—you type <command>gmake install</command> and lo! the
2296 right things get compiled and installed in the right places. Our
2297 goal is to make this happen often, but somehow it often doesn't;
2298 instead some weird error message eventually emerges from the
2299 bowels of a directory you didn't know existed.</para>
2301 <para>The purpose of this section is to give you a road-map to
2302 help you figure out what is going right and what is going
2306 <title>Debugging</title>
2308 <para>Debugging <filename>Makefile</filename>s is something of a
2309 black art, but here's a couple of tricks that we find
2310 particularly useful. The following command allows you to see
2311 the contents of any make variable in the context of the current
2312 <filename>Makefile</filename>:</para>
2314 <screen>$ make show VALUE=HS_SRCS</screen>
2316 <para>where you can replace <literal>HS_SRCS</literal> with the
2317 name of any variable you wish to see the value of.</para>
2319 <para>GNU make has a <option>-d</option> option which generates
2320 a dump of the decision procedure used to arrive at a conclusion
2321 about which files should be recompiled. Sometimes useful for
2322 tracking down problems with superfluous or missing
2323 recompilations.</para>
2327 <title>A small project</title>
2329 <para>To get started, let us look at the
2330 <filename>Makefile</filename> for an imaginary small
2331 <literal>fptools</literal> project, <literal>small</literal>.
2332 Each project in <literal>fptools</literal> has its own directory
2333 in <constant>FPTOOLS_TOP</constant>, so the
2334 <literal>small</literal> project will have its own directory
2335 <constant>FPOOLS_TOP/small/</constant>. Inside the
2336 <filename>small/</filename> directory there will be a
2337 <filename>Makefile</filename>, looking something like
2340 <indexterm><primary>Makefile, minimal</primary></indexterm>
2342 <programlisting># Makefile for fptools project "small"
2345 include $(TOP)/mk/boilerplate.mk
2347 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2350 include $(TOP)/target.mk</programlisting>
2352 <para>this <filename>Makefile</filename> has three
2357 <para>The first section includes
2360 One of the most important
2361 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2362 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2367 a file of “boilerplate” code from the level
2368 above (which in this case will be
2369 <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2370 As its name suggests, <filename>boilerplate.mk</filename>
2371 consists of a large quantity of standard
2372 <filename>Makefile</filename> code. We discuss this
2373 boilerplate in more detail in <xref linkend="sec-boiler"/>.
2374 <indexterm><primary>include, directive in
2375 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2376 inclusion</primary></indexterm></para>
2378 <para>Before the <literal>include</literal> statement, you
2379 must define the <command>make</command> variable
2380 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2381 to be the directory containing the <filename>mk</filename>
2382 directory in which the <filename>boilerplate.mk</filename>
2383 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2385 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
2388 <para>Why? Because the <filename>boilerplate.mk</filename>
2389 file needs to know where it is, so that it can, in turn,
2390 <literal>include</literal> other files. (Unfortunately,
2391 when an <literal>include</literal>d file does an
2392 <literal>include</literal>, the filename is treated relative
2393 to the directory in which <command>gmake</command> is being
2394 run, not the directory in which the
2395 <literal>include</literal>d sits.) In general,
2396 <emphasis>every file <filename>foo.mk</filename> assumes
2398 <filename>$(TOP)/mk/foo.mk</filename>
2399 refers to itself.</emphasis> It is up to the
2400 <filename>Makefile</filename> doing the
2401 <literal>include</literal> to ensure this is the case.</para>
2403 <para>Files intended for inclusion in other
2404 <filename>Makefile</filename>s are written to have the
2405 following property: <emphasis>after
2406 <filename>foo.mk</filename> is <literal>include</literal>d,
2407 it leaves <constant>TOP</constant> containing the same value
2408 as it had just before the <literal>include</literal>
2409 statement</emphasis>. In our example, this invariant
2410 guarantees that the <literal>include</literal> for
2411 <filename>target.mk</filename> will look in the same
2412 directory as that for <filename>boilerplate.mk</filename>.</para>
2416 <para> The second section defines the following standard
2417 <command>make</command> variables:
2418 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2419 (the source files from which is to be built), and
2420 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2421 (the executable binary to be built). We will discuss in
2422 more detail what the “standard variables” are,
2423 and how they affect what happens, in <xref
2424 linkend="sec-targets"/>.</para>
2426 <para>The definition for <constant>SRCS</constant> uses the
2427 useful GNU <command>make</command> construct
2428 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2429 which expands to a list of all the files matching the
2430 pattern <literal>pat</literal> in the current directory. In
2431 this example, <constant>SRCS</constant> is set to the list
2432 of all the <filename>.lhs</filename> and
2433 <filename>.c</filename> files in the directory. (Let's
2434 suppose there is one of each, <filename>Foo.lhs</filename>
2435 and <filename>Baz.c</filename>.)</para>
2439 <para>The last section includes a second file of standard
2441 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2442 It contains the rules that tell <command>gmake</command> how
2443 to make the standard targets (<xref
2444 linkend="sec-standard-targets"/>). Why, you ask, can't this
2445 standard code be part of
2446 <filename>boilerplate.mk</filename>? Good question. We
2447 discuss the reason later, in <xref
2448 linkend="sec-boiler-arch"/>.</para>
2450 <para>You do not <emphasis>have</emphasis> to
2451 <literal>include</literal> the
2452 <filename>target.mk</filename> file. Instead, you can write
2453 rules of your own for all the standard targets. Usually,
2454 though, you will find quite a big payoff from using the
2455 canned rules in <filename>target.mk</filename>; the price
2456 tag is that you have to understand what canned rules get
2457 enabled, and what they do (<xref
2458 linkend="sec-targets"/>).</para>
2462 <para>In our example <filename>Makefile</filename>, most of the
2463 work is done by the two <literal>include</literal>d files. When
2464 you say <command>gmake all</command>, the following things
2469 <para><command>gmake</command> figures out that the object
2470 files are <filename>Foo.o</filename> and
2471 <filename>Baz.o</filename>.</para>
2475 <para>It uses a boilerplate pattern rule to compile
2476 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2477 using a Haskell compiler. (Which one? That is set in the
2478 build configuration.)</para>
2482 <para>It uses another standard pattern rule to compile
2483 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2484 using a C compiler. (Ditto.)</para>
2488 <para>It links the resulting <filename>.o</filename> files
2489 together to make <literal>small</literal>, using the Haskell
2490 compiler to do the link step. (Why not use
2491 <command>ld</command>? Because the Haskell compiler knows
2492 what standard libraries to link in. How did
2493 <command>gmake</command> know to use the Haskell compiler to
2494 do the link, rather than the C compiler? Because we set the
2495 variable <constant>HS_PROG</constant> rather than
2496 <constant>C_PROG</constant>.)</para>
2500 <para>All <filename>Makefile</filename>s should follow the above
2501 three-section format.</para>
2505 <title>A larger project</title>
2507 <para>Larger projects are usually structured into a number of
2508 sub-directories, each of which has its own
2509 <filename>Makefile</filename>. (In very large projects, this
2510 sub-structure might be iterated recursively, though that is
2511 rare.) To give you the idea, here's part of the directory
2512 structure for the (rather large) GHC project:</para>
2514 <programlisting>$(FPTOOLS_TOP)/ghc/
2521 ...source files for documentation...
2524 ...source files for driver...
2527 parser/...source files for parser...
2528 renamer/...source files for renamer...
2529 ...etc...</programlisting>
2531 <para>The sub-directories <filename>docs</filename>,
2532 <filename>driver</filename>, <filename>compiler</filename>, and
2533 so on, each contains a sub-component of GHC, and each has its
2534 own <filename>Makefile</filename>. There must also be a
2535 <filename>Makefile</filename> in
2536 <filename>$(FPTOOLS_TOP)/ghc</filename>.
2537 It does most of its work by recursively invoking
2538 <command>gmake</command> on the <filename>Makefile</filename>s
2539 in the sub-directories. We say that
2540 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2541 <filename>Makefile</filename></emphasis>, because it does little
2542 except organise its children, while the
2543 <filename>Makefile</filename>s in the sub-directories are all
2544 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2545 principle the sub-directories might themselves contain a
2546 non-leaf <filename>Makefile</filename> and several
2547 sub-sub-directories, but that does not happen in GHC.)</para>
2549 <para>The <filename>Makefile</filename> in
2550 <filename>ghc/compiler</filename> is considered a leaf
2551 <filename>Makefile</filename> even though the
2552 <filename>ghc/compiler</filename> has sub-directories, because
2553 these sub-directories do not themselves have
2554 <filename>Makefile</filename>s in them. They are just used to
2555 structure the collection of modules that make up GHC, but all
2556 are managed by the single <filename>Makefile</filename> in
2557 <filename>ghc/compiler</filename>.</para>
2559 <para>You will notice that <filename>ghc/</filename> also
2560 contains a directory <filename>ghc/mk/</filename>. It contains
2561 GHC-specific <filename>Makefile</filename> boilerplate code.
2562 More precisely:</para>
2566 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2567 at the top of <filename>ghc/Makefile</filename>, and of all
2568 the leaf <filename>Makefile</filename>s in the
2569 sub-directories. It in turn <literal>include</literal>s the
2570 main boilerplate file
2571 <filename>mk/boilerplate.mk</filename>.</para>
2575 <para><filename>ghc/mk/target.mk</filename> is
2576 <literal>include</literal>d at the bottom of
2577 <filename>ghc/Makefile</filename>, and of all the leaf
2578 <filename>Makefile</filename>s in the sub-directories. It
2579 in turn <literal>include</literal>s the file
2580 <filename>mk/target.mk</filename>.</para>
2584 <para>So these two files are the place to look for GHC-wide
2585 customisation of the standard boilerplate.</para>
2588 <sect2 id="sec-boiler-arch">
2589 <title>Boilerplate architecture</title>
2590 <indexterm><primary>boilerplate architecture</primary></indexterm>
2592 <para>Every <filename>Makefile</filename> includes a
2593 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2594 file at the top, and
2595 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2596 file at the bottom. In this section we discuss what is in these
2597 files, and why there have to be two of them. In general:</para>
2601 <para><filename>boilerplate.mk</filename> consists of:</para>
2605 <para><emphasis>Definitions of millions of
2606 <command>make</command> variables</emphasis> that
2607 collectively specify the build configuration. Examples:
2608 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2609 the options to feed to the Haskell compiler;
2610 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2611 the sub-directories to enable within the
2612 <literal>nofib</literal> project;
2613 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2614 the name of the Haskell compiler to use when compiling
2615 GHC in the <literal>ghc</literal> project.</para>
2619 <para><emphasis>Standard pattern rules</emphasis> that
2620 tell <command>gmake</command> how to construct one file
2621 from another.</para>
2625 <para><filename>boilerplate.mk</filename> needs to be
2626 <literal>include</literal>d at the <emphasis>top</emphasis>
2627 of each <filename>Makefile</filename>, so that the user can
2628 replace the boilerplate definitions or pattern rules by
2629 simply giving a new definition or pattern rule in the
2630 <filename>Makefile</filename>. <command>gmake</command>
2631 simply takes the last definition as the definitive one.</para>
2633 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2634 definitions, it is also quite common to
2635 <emphasis>augment</emphasis> them. For example, a
2636 <filename>Makefile</filename> might say:</para>
2638 <programlisting>SRC_HC_OPTS += -O</programlisting>
2640 <para>thereby adding “<option>-O</option>” to
2642 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2646 <para><filename>target.mk</filename> contains
2647 <command>make</command> rules for the standard targets
2648 described in <xref linkend="sec-standard-targets"/>. These
2649 rules are selectively included, depending on the setting of
2650 certain <command>make</command> variables. These variables
2651 are usually set in the middle section of the
2652 <filename>Makefile</filename> between the two
2653 <literal>include</literal>s.</para>
2655 <para><filename>target.mk</filename> must be included at the
2656 end (rather than being part of
2657 <filename>boilerplate.mk</filename>) for several tiresome
2663 <para><command>gmake</command> commits target and
2664 dependency lists earlier than it should. For example,
2665 <filename>target.mk</filename> has a rule that looks
2668 <programlisting>$(HS_PROG) : $(OBJS)
2669 $(HC) $(LD_OPTS) $< -o $@</programlisting>
2671 <para>If this rule was in
2672 <filename>boilerplate.mk</filename> then
2673 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2675 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2676 would not have their final values at the moment
2677 <command>gmake</command> encountered the rule. Alas,
2678 <command>gmake</command> takes a snapshot of their
2679 current values, and wires that snapshot into the rule.
2680 (In contrast, the commands executed when the rule
2681 “fires” are only substituted at the moment
2682 of firing.) So, the rule must follow the definitions
2683 given in the <filename>Makefile</filename> itself.</para>
2687 <para>Unlike pattern rules, ordinary rules cannot be
2688 overriden or replaced by subsequent rules for the same
2689 target (at least, not without an error message).
2690 Including ordinary rules in
2691 <filename>boilerplate.mk</filename> would prevent the
2692 user from writing rules for specific targets in specific
2697 <para>There are a couple of other reasons I've
2698 forgotten, but it doesn't matter too much.</para>
2705 <sect2 id="sec-boiler">
2706 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2707 <indexterm><primary>boilerplate.mk</primary></indexterm>
2709 <para>If you look at
2710 <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
2711 you will find that it consists of the following sections, each
2712 held in a separate file:</para>
2716 <term><filename>config.mk</filename>
2717 <indexterm><primary>config.mk</primary></indexterm>
2720 <para>is the build configuration file we discussed at
2721 length in <xref linkend="sec-build-config"/>.</para>
2726 <term><filename>paths.mk</filename>
2727 <indexterm><primary>paths.mk</primary></indexterm>
2730 <para>defines <command>make</command> variables for
2731 pathnames and file lists. This file contains code for
2732 automatically compiling lists of source files and deriving
2733 lists of object files from those. The results can be
2734 overriden in the <filename>Makefile</filename>, but in
2735 most cases the automatic setup should do the right
2738 <para>The following variables may be set in the
2739 <filename>Makefile</filename> to affect how the automatic
2740 source file search is done:</para>
2744 <term><literal>ALL_DIRS</literal>
2745 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
2748 <para>Set to a list of directories to search in
2749 addition to the current directory for source
2755 <term><literal>EXCLUDED_SRCS</literal>
2756 <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
2759 <para>Set to a list of source files (relative to the
2760 current directory) to omit from the automatic
2761 search. The source searching machinery is clever
2762 enough to know that if you exclude a source file
2763 from which other sources are derived, then the
2764 derived sources should also be excluded. For
2765 example, if you set <literal>EXCLUDED_SRCS</literal>
2766 to include <filename>Foo.y</filename>, then
2767 <filename>Foo.hs</filename> will also be
2773 <term><literal>EXTRA_SRCS</literal>
2774 <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
2777 <para>Set to a list of extra source files (perhaps
2778 in directories not listed in
2779 <literal>ALL_DIRS</literal>) that should be
2785 <para>The results of the automatic source file search are
2786 placed in the following make variables:</para>
2790 <term><literal>SRCS</literal>
2791 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2794 <para>All source files found, sorted and without
2795 duplicates, including those which might not exist
2796 yet but will be derived from other existing sources.
2797 <literal>SRCS</literal> <emphasis>can</emphasis> be
2798 overriden if necessary, in which case the variables
2799 below will follow suit.</para>
2804 <term><literal>HS_SRCS</literal>
2805 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2808 <para>all Haskell source files in the current
2809 directory, including those derived from other source
2810 files (eg. Happy sources also give rise to Haskell
2816 <term><literal>HS_OBJS</literal>
2817 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2820 <para>Object files derived from
2821 <literal>HS_SRCS</literal>.</para>
2826 <term><literal>HS_IFACES</literal>
2827 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2830 <para>Interface files (<literal>.hi</literal> files)
2831 derived from <literal>HS_SRCS</literal>.</para>
2836 <term><literal>C_SRCS</literal>
2837 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2840 <para>All C source files found.</para>
2845 <term><literal>C_OBJS</literal>
2846 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2849 <para>Object files derived from
2850 <literal>C_SRCS</literal>.</para>
2855 <term><literal>SCRIPT_SRCS</literal>
2856 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2859 <para>All script source files found
2860 (<literal>.lprl</literal> files).</para>
2865 <term><literal>SCRIPT_OBJS</literal>
2866 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2869 <para><quote>object</quote> files derived from
2870 <literal>SCRIPT_SRCS</literal>
2871 (<literal>.prl</literal> files).</para>
2876 <term><literal>HSC_SRCS</literal>
2877 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2880 <para>All <literal>hsc2hs</literal> source files
2881 (<literal>.hsc</literal> files).</para>
2886 <term><literal>HAPPY_SRCS</literal>
2887 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2890 <para>All <literal>happy</literal> source files
2891 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2896 <term><literal>OBJS</literal>
2897 <indexterm><primary>OBJS</primary></indexterm>
2900 <para>the concatenation of
2901 <literal>$(HS_OBJS)</literal>,
2902 <literal>$(C_OBJS)</literal>, and
2903 <literal>$(SCRIPT_OBJS)</literal>.</para>
2908 <para>Any or all of these definitions can easily be
2909 overriden by giving new definitions in your
2910 <filename>Makefile</filename>.</para>
2912 <para>What, exactly, does <filename>paths.mk</filename>
2913 consider a <quote>source file</quote> to be? It's based
2914 on the file's suffix (e.g. <filename>.hs</filename>,
2915 <filename>.lhs</filename>, <filename>.c</filename>,
2916 <filename>.hy</filename>, etc), but this is the kind of
2917 detail that changes, so rather than enumerate the source
2918 suffices here the best thing to do is to look in
2919 <filename>paths.mk</filename>.</para>
2924 <term><filename>opts.mk</filename>
2925 <indexterm><primary>opts.mk</primary></indexterm>
2928 <para>defines <command>make</command> variables for option
2929 strings to pass to each program. For example, it defines
2930 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2931 the option strings to pass to the Haskell compiler. See
2932 <xref linkend="sec-suffix"/>.</para>
2937 <term><filename>suffix.mk</filename>
2938 <indexterm><primary>suffix.mk</primary></indexterm>
2941 <para>defines standard pattern rules—see <xref
2942 linkend="sec-suffix"/>.</para>
2947 <para>Any of the variables and pattern rules defined by the
2948 boilerplate file can easily be overridden in any particular
2949 <filename>Makefile</filename>, because the boilerplate
2950 <literal>include</literal> comes first. Definitions after this
2951 <literal>include</literal> directive simply override the default
2952 ones in <filename>boilerplate.mk</filename>.</para>
2955 <sect2 id="sec-platforms">
2956 <title>Platform settings</title>
2957 <indexterm><primary>Platform settings</primary>
2960 <para>There are three platforms of interest when building GHC:</para>
2964 <term>The <emphasis>build</emphasis> platform</term>
2966 <para>The platform on which we are doing this build.</para>
2971 <term>The <emphasis>host</emphasis> platform</term>
2973 <para>The platform on which these binaries will run.</para>
2978 <term>The <emphasis>target</emphasis> platform</term>
2980 <para>The platform for which this compiler will generate code.</para>
2985 <para>These platforms are set when running the
2986 <literal>configure</literal> script, using the
2987 <option>--build</option>, <option>--host</option>, and
2988 <option>--target</option> options. The <filename>mk/config.mk</filename>
2989 file defines several symbols related to the platform settings (see
2990 <filename>mk/config.mk</filename> for details).</para>
2992 <para>We don't currently support build & host being different, because
2993 the build process creates binaries that are both run during the build,
2994 and also installed.</para>
2996 <para>If host and target are different, then we are building a
2997 cross-compiler. For GHC, this means a compiler
2998 which will generate intermediate .hc files to port to the target
2999 architecture for bootstrapping. The libraries and stage 2 compiler
3000 will be built as HC files for the target system (see <xref
3001 linkend="sec-porting-ghc" /> for details.</para>
3003 <para>More details on when to use BUILD, HOST or TARGET can be found in
3004 the comments in <filename>config.mk</filename>.</para>
3007 <sect2 id="sec-suffix">
3008 <title>Pattern rules and options</title>
3009 <indexterm><primary>Pattern rules</primary></indexterm>
3012 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
3013 defines standard <emphasis>pattern rules</emphasis> that say how
3014 to build one kind of file from another, for example, how to
3015 build a <filename>.o</filename> file from a
3016 <filename>.c</filename> file. (GNU <command>make</command>'s
3017 <emphasis>pattern rules</emphasis> are more powerful and easier
3018 to use than Unix <command>make</command>'s <emphasis>suffix
3019 rules</emphasis>.)</para>
3021 <para>Almost all the rules look something like this:</para>
3023 <programlisting>%.o : %.c
3025 $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
3027 <para>Here's how to understand the rule. It says that
3028 <emphasis>something</emphasis><filename>.o</filename> (say
3029 <filename>Foo.o</filename>) can be built from
3030 <emphasis>something</emphasis><filename>.c</filename>
3031 (<filename>Foo.c</filename>), by invoking the C compiler (path
3032 name held in <constant>$(CC)</constant>), passing to it
3033 the options <constant>$(CC_OPTS)</constant> and
3034 the rule's dependent file of the rule
3035 <literal>$<</literal> (<filename>Foo.c</filename> in
3036 this case), and putting the result in the rule's target
3037 <literal>$@</literal> (<filename>Foo.o</filename> in this
3040 <para>Every program is held in a <command>make</command>
3041 variable defined in <filename>mk/config.mk</filename>—look
3042 in <filename>mk/config.mk</filename> for the complete list. One
3043 important one is the Haskell compiler, which is called
3044 <constant>$(HC)</constant>.</para>
3046 <para>Every program's options are are held in a
3047 <command>make</command> variables called
3048 <constant><prog>_OPTS</constant>. the
3049 <constant><prog>_OPTS</constant> variables are
3050 defined in <filename>mk/opts.mk</filename>. Almost all of them
3051 are defined like this:</para>
3053 <programlisting>CC_OPTS = \
3054 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
3056 <para>The four variables from which
3057 <constant>CC_OPTS</constant> is built have the following
3062 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3064 <para>options passed to all C compilations.</para>
3069 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3071 <para>options passed to C compilations for way
3072 <literal><way></literal>. For example,
3073 <constant>WAY_mp_CC_OPTS</constant>
3074 gives options to pass to the C compiler when compiling way
3075 <literal>mp</literal>. The variable
3076 <constant>WAY_CC_OPTS</constant> holds
3077 options to pass to the C compiler when compiling the
3078 standard way. (<xref linkend="sec-ways"/> dicusses
3079 multi-way compilation.)</para>
3084 <term><constant><module>_CC_OPTS</constant>:</term>
3086 <para>options to pass to the C compiler that are specific
3087 to module <literal><module></literal>. For example,
3088 <constant>SMap_CC_OPTS</constant> gives the
3089 specific options to pass to the C compiler when compiling
3090 <filename>SMap.c</filename>.</para>
3095 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3097 <para>extra options to pass to all C compilations. This
3098 is intended for command line use, thus:</para>
3100 <screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
3106 <sect2 id="sec-targets">
3107 <title>The main <filename>mk/target.mk</filename> file</title>
3108 <indexterm><primary>target.mk</primary></indexterm>
3110 <para><filename>target.mk</filename> contains canned rules for
3111 all the standard targets described in <xref
3112 linkend="sec-standard-targets"/>. It is complicated by the fact
3113 that you don't want all of these rules to be active in every
3114 <filename>Makefile</filename>. Rather than have a plethora of
3115 tiny files which you can include selectively, there is a single
3116 file, <filename>target.mk</filename>, which selectively includes
3117 rules based on whether you have defined certain variables in
3118 your <filename>Makefile</filename>. This section explains what
3119 rules you get, what variables control them, and what the rules
3120 do. Hopefully, you will also get enough of an idea of what is
3121 supposed to happen that you can read and understand any weird
3122 special cases yourself.</para>
3126 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3128 <para>If <constant>HS_PROG</constant> is defined,
3129 you get rules with the following targets:</para>
3133 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3135 <para>itself. This rule links
3136 <constant>$(OBJS)</constant> with the Haskell
3137 runtime system to get an executable called
3138 <constant>$(HS_PROG)</constant>.</para>
3143 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3146 <constant>$(HS_PROG)</constant> in
3147 <constant>$(bindir)</constant>.</para>
3156 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3158 <para>is similar to <constant>HS_PROG</constant>,
3159 except that the link step links
3160 <constant>$(C_OBJS)</constant> with the C
3161 runtime system.</para>
3166 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3168 <para>is similar to <constant>HS_PROG</constant>,
3169 except that it links
3170 <constant>$(LIB_OBJS)</constant> to make the
3171 library archive <constant>$(LIBRARY)</constant>,
3172 and <literal>install</literal> installs it in
3173 <constant>$(libdir)</constant>.</para>
3178 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3180 <para>…</para>
3185 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3187 <para>…</para>
3192 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3194 <para>If <constant>HS_SRCS</constant> is defined
3195 and non-empty, a rule for the target
3196 <literal>depend</literal> is included, which generates
3197 dependency information for Haskell programs. Similarly
3198 for <constant>C_SRCS</constant>.</para>
3203 <para>All of these rules are “double-colon” rules,
3206 <programlisting>install :: $(HS_PROG)
3207 ...how to install it...</programlisting>
3209 <para>GNU <command>make</command> treats double-colon rules as
3210 separate entities. If there are several double-colon rules for
3211 the same target it takes each in turn and fires it if its
3212 dependencies say to do so. This means that you can, for
3213 example, define both <constant>HS_PROG</constant> and
3214 <constant>LIBRARY</constant>, which will generate two rules for
3215 <literal>install</literal>. When you type <command>gmake
3216 install</command> both rules will be fired, and both the program
3217 and the library will be installed, just as you wanted.</para>
3220 <sect2 id="sec-subdirs">
3221 <title>Recursion</title>
3222 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3223 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3225 <para>In leaf <filename>Makefile</filename>s the variable
3226 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3227 is undefined. In non-leaf <filename>Makefile</filename>s,
3228 <constant>SUBDIRS</constant> is set to the list of
3229 sub-directories that contain subordinate
3230 <filename>Makefile</filename>s. <emphasis>It is up to you to
3231 set <constant>SUBDIRS</constant> in the
3232 <filename>Makefile</filename>.</emphasis> There is no automation
3233 here—<constant>SUBDIRS</constant> is too important to
3236 <para>When <constant>SUBDIRS</constant> is defined,
3237 <filename>target.mk</filename> includes a rather neat rule for
3238 the standard targets (<xref linkend="sec-standard-targets"/> that
3239 simply invokes <command>make</command> recursively in each of
3240 the sub-directories.</para>
3242 <para><emphasis>These recursive invocations are guaranteed to
3243 occur in the order in which the list of directories is specified
3244 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3245 be important. For example, when you say <command>gmake
3246 boot</command> it can be important that the recursive invocation
3247 of <command>make boot</command> is done in one sub-directory
3248 (the include files, say) before another (the source files).
3249 Generally, put the most independent sub-directory first, and the
3250 most dependent last.</para>
3253 <sect2 id="sec-ways">
3254 <title>Way management</title>
3255 <indexterm><primary>way management</primary></indexterm>
3257 <para>We sometimes want to build essentially the same system in
3258 several different “ways”. For example, we want to build GHC's
3259 <literal>Prelude</literal> libraries with and without profiling,
3260 so that there is an appropriately-built library archive to link
3261 with when the user compiles his program. It would be possible
3262 to have a completely separate build tree for each such “way”,
3263 but it would be horribly bureaucratic, especially since often
3264 only parts of the build tree need to be constructed in multiple
3268 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3269 contains some clever magic to allow you to build several
3270 versions of a system; and to control locally how many versions
3271 are built and how they differ. This section explains the
3274 <para>The files for a particular way are distinguished by
3275 munging the suffix. The <quote>normal way</quote> is always
3276 built, and its files have the standard suffices
3277 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3278 In addition, you can build one or more extra ways, each
3279 distinguished by a <emphasis>way tag</emphasis>. The object
3280 files and interface files for one of these extra ways are
3281 distinguished by their suffix. For example, way
3282 <literal>mp</literal> has files
3283 <filename>.mp_o</filename> and
3284 <filename>.mp_hi</filename>. Library archives have their
3285 way tag the other side of the dot, for boring reasons; thus,
3286 <filename>libHS_mp.a</filename>.</para>
3288 <para>A <command>make</command> variable called
3289 <constant>way</constant> holds the current way tag.
3290 <emphasis><constant>way</constant> is only ever set on the
3291 command line of <command>gmake</command></emphasis> (usually in
3292 a recursive invocation of <command>gmake</command> by the
3293 system). It is never set inside a
3294 <filename>Makefile</filename>. So it is a global constant for
3295 any one invocation of <command>gmake</command>. Two other
3296 <command>make</command> variables,
3297 <constant>way_</constant> and
3298 <constant>_way</constant> are immediately derived from
3299 <constant>$(way)</constant> and never altered. If
3300 <constant>way</constant> is not set, then neither are
3301 <constant>way_</constant> and
3302 <constant>_way</constant>, and the invocation of
3303 <command>make</command> will build the <quote>normal
3304 way</quote>. If <constant>way</constant> is set, then the other
3305 two variables are set in sympathy. For example, if
3306 <constant>$(way)</constant> is “<literal>mp</literal>”,
3307 then <constant>way_</constant> is set to
3308 “<literal>mp_</literal>” and
3309 <constant>_way</constant> is set to
3310 “<literal>_mp</literal>”. These three variables are
3311 then used when constructing file names.</para>
3313 <para>So how does <command>make</command> ever get recursively
3314 invoked with <constant>way</constant> set? There are two ways
3315 in which this happens:</para>
3319 <para>For some (but not all) of the standard targets, when
3320 in a leaf sub-directory, <command>make</command> is
3321 recursively invoked for each way tag in
3322 <constant>$(WAYS)</constant>. You set
3323 <constant>WAYS</constant> in the
3324 <filename>Makefile</filename> to the list of way tags you
3325 want these targets built for. The mechanism here is very
3326 much like the recursive invocation of
3327 <command>make</command> in sub-directories (<xref
3328 linkend="sec-subdirs"/>). It is up to you to set
3329 <constant>WAYS</constant> in your
3330 <filename>Makefile</filename>; this is how you control what
3331 ways will get built.</para>
3335 <para>For a useful collection of targets (such as
3336 <filename>libHS_mp.a</filename>,
3337 <filename>Foo.mp_o</filename>) there is a rule which
3338 recursively invokes <command>make</command> to make the
3339 specified target, setting the <constant>way</constant>
3340 variable. So if you say <command>gmake
3341 Foo.mp_o</command> you should see a recursive
3342 invocation <command>gmake Foo.mp_o way=mp</command>,
3343 and <emphasis>in this recursive invocation the pattern rule
3344 for compiling a Haskell file into a <filename>.o</filename>
3345 file will match</emphasis>. The key pattern rules (in
3346 <filename>suffix.mk</filename>) look like this:
3348 <programlisting>%.$(way_)o : %.lhs
3349 $(HC) $(HC_OPTS) $< -o $@</programlisting>
3355 <para>You can invoke <command>make</command> with a
3356 particular <literal>way</literal> setting yourself, in order
3357 to build files related to a particular
3358 <literal>way</literal> in the current directory. eg.
3360 <screen>$ make way=p</screen>
3362 will build files for the profiling way only in the current
3369 <title>When the canned rule isn't right</title>
3371 <para>Sometimes the canned rule just doesn't do the right thing.
3372 For example, in the <literal>nofib</literal> suite we want the
3373 link step to print out timing information. The thing to do here
3374 is <emphasis>not</emphasis> to define
3375 <constant>HS_PROG</constant> or
3376 <constant>C_PROG</constant>, and instead define a special
3377 purpose rule in your own <filename>Makefile</filename>. By
3378 using different variable names you will avoid the canned rules
3379 being included, and conflicting with yours.</para>
3383 <sect1 id="building-docs">
3384 <title>Building the documentation</title>
3386 <sect2 id="pre-supposed-doc-tools">
3387 <title>Tools for building the Documentation</title>
3389 <para>The following additional tools are required if you want to
3390 format the documentation that comes with the
3391 <literal>fptools</literal> projects:</para>
3396 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3397 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3400 <para>Much of our documentation is written in DocBook XML, instructions
3401 on installing and configuring the DocBook tools are below.</para>
3407 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3408 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3411 <para>A decent TeX distribution is required if you want to
3412 produce printable documentation. We recomment teTeX,
3413 which includes just about everything you need.</para>
3419 <indexterm><primary>Haddock</primary></indexterm>
3422 <para>Haddock is a Haskell documentation tool that we use
3423 for automatically generating documentation from the
3424 library source code. It is an <literal>fptools</literal>
3425 project in itself. To build documentation for the
3426 libraries (<literal>fptools/libraries</literal>) you
3427 should check out and build Haddock in
3428 <literal>fptools/haddock</literal>. Haddock requires GHC
3436 <title>Installing the DocBook tools</title>
3439 <title>Installing the DocBook tools on Linux</title>
3441 <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
3442 you probably have working DocBook tools already installed. The
3443 configure script should detect your setup and you're away.</para>
3445 <para>If you don't have DocBook tools installed, and you are
3446 using a system that can handle RPM packages, you can use <ulink
3447 url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
3448 packages for your system. Search for the packages
3449 <literal>docbook-dtd</literal>,
3450 <literal>docbook-xsl-stylesheets</literal>,
3451 <literal>libxslt</literal>,
3452 <literal>libxml2</literal>,
3453 <literal>fop</literal>,
3454 <literal>xmltex</literal>, and
3455 <literal>dvips</literal>.</para>
3459 <title>Installing DocBook on FreeBSD</title>
3461 <para>On FreeBSD systems, the easiest way to get DocBook up
3462 and running is to install it from the ports tree or a
3463 pre-compiled package (packages are available from your local
3464 FreeBSD mirror site).</para>
3466 <para>To use the ports tree, do this:
3467 <screen>$ cd /usr/ports/textproc/docproj
3468 $ make install</screen>
3469 This installs the FreeBSD documentation project tools, which
3470 includes everything needed to format the GHC
3471 documentation.</para>
3475 <title>Installing from binaries on Windows</title>
3477 <para>Probably the fastest route to a working DocBook environment on
3478 Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
3479 with the complete <literal>Doc</literal> category. If you are using
3480 <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
3481 have to help <command>configure</command> a little bit: Set the
3482 environment variables <envar>XmllintCmd</envar> and
3483 <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
3484 <command>xmllint</command> and <command>xsltproc</command>,
3485 respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
3486 of the directory where the XSL stylesheets are installed,
3487 e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
3490 <para>If you want to build HTML Help, you have to install the
3491 <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
3492 too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
3498 <title>Configuring the DocBook tools</title>
3500 <para>Once the DocBook tools are installed, the configure script
3501 will detect them and set up the build system accordingly. If you
3502 have a system that isn't supported, let us know, and we'll try
3507 <title>Building the documentation</title>
3509 <para>To build documentation in a certain format, you can
3510 say, for example,</para>
3512 <screen>$ make html</screen>
3514 <para>to build HTML documentation below the current directory.
3515 The available formats are: <literal>dvi</literal>,
3516 <literal>ps</literal>, <literal>pdf</literal>,
3517 <literal>html</literal>, and <literal>rtf</literal>. Note that
3518 not all documentation can be built in all of these formats: HTML
3519 documentation is generally supported everywhere, and DocBook
3520 documentation might support the other formats (depending on what
3521 other tools you have installed).</para>
3523 <para>All of these targets are recursive; that is, saying
3524 <literal>make html</literal> will make HTML docs for all the
3525 documents recursively below the current directory.</para>
3527 <para>Because there are many different formats that the DocBook
3528 documentation can be generated in, you have to select which ones
3529 you want by setting the <literal>XMLDocWays</literal> variable
3530 to a list of them. For example, in
3531 <filename>build.mk</filename> you might have a line:</para>
3533 <screen>XMLDocWays = html ps</screen>
3535 <para>This will cause the documentation to be built in the requested
3536 formats as part of the main build (the default is not to build
3537 any documentation at all).</para>
3541 <title>Installing the documentation</title>
3543 <para>To install the documentation, use:</para>
3545 <screen>$ make install-docs</screen>
3547 <para>This will install the documentation into
3548 <literal>$(datadir)</literal> (which defaults to
3549 <literal>$(prefix)/share</literal>). The exception is HTML
3550 documentation, which goes into
3551 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3553 <para>Note that unless you set <literal>$(XMLDocWays)</literal>
3554 to a list of formats, the <literal>install-docs</literal> target
3555 won't do anything for DocBook XML documentation.</para>
3561 <sect1 id="sec-porting-ghc">
3562 <title>Porting GHC</title>
3564 <para>This section describes how to port GHC to a currenly
3565 unsupported platform. There are two distinct
3566 possibilities:</para>
3570 <para>The hardware architecture for your system is already
3571 supported by GHC, but you're running an OS that isn't
3572 supported (or perhaps has been supported in the past, but
3573 currently isn't). This is the easiest type of porting job,
3574 but it still requires some careful bootstrapping. Proceed to
3575 <xref linkend="sec-booting-from-hc"/>.</para>
3579 <para>Your system's hardware architecture isn't supported by
3580 GHC. This will be a more difficult port (though by comparison
3581 perhaps not as difficult as porting gcc). Proceed to <xref
3582 linkend="unregisterised-porting"/>.</para>
3586 <sect2 id="sec-booting-from-hc">
3587 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3589 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3590 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3591 <indexterm><primary>porting GHC</primary></indexterm>
3593 <para>Bootstrapping GHC on a system without GHC already
3594 installed is achieved by taking the intermediate C files (known
3595 as HC files) from another GHC compilation, compiling them using gcc to
3596 get a working GHC.</para>
3598 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3599 from C. We recommend using GHC 6.0.1 or
3600 later.</emphasis></para>
3602 <para>HC files are platform-dependent, so you have to get a set
3603 that were generated on <emphasis>the same platform</emphasis>. There
3604 may be some supplied on the GHC download page, otherwise you'll have to
3605 compile some up yourself, or start from
3606 <emphasis>unregisterised</emphasis> HC files - see <xref
3607 linkend="unregisterised-porting"/>.</para>
3609 <para>The following steps should result in a working GHC build
3610 with full libraries:</para>
3614 <para>Unpack the HC files on top of a fresh source tree
3615 (make sure the source tree version matches the version of
3616 the HC files <emphasis>exactly</emphasis>!). This will
3617 place matching <filename>.hc</filename> files next to the
3618 corresponding Haskell source (<filename>.hs</filename> or
3619 <filename>.lhs</filename>) in the compiler subdirectory
3620 <filename>ghc/compiler</filename> and in the libraries
3621 (subdirectories of <filename>hslibs</filename> and
3622 <literal>libraries</literal>).</para>
3626 <para>The actual build process is fully automated by the
3627 <filename>hc-build</filename> script located in the
3628 <filename>distrib</filename> directory. If you eventually
3629 want to install GHC into the directory
3630 <replaceable>dir</replaceable>, the following
3631 command will execute the whole build process (it won't
3632 install yet):</para>
3634 <screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
3635 <indexterm><primary>--hc-build</primary></indexterm>
3637 <para>By default, the installation directory is
3638 <filename>/usr/local</filename>. If that is what you want,
3639 you may omit the argument to <filename>hc-build</filename>.
3640 Generally, any option given to <filename>hc-build</filename>
3641 is passed through to the configuration script
3642 <filename>configure</filename>. If
3643 <filename>hc-build</filename> successfully completes the
3644 build process, you can install the resulting system, as
3647 <screen>$ make install</screen>
3652 <sect2 id="unregisterised-porting">
3653 <title>Porting GHC to a new architecture</title>
3655 <para>The first step in porting to a new architecture is to get
3656 an <firstterm>unregisterised</firstterm> build working. An
3657 unregisterised build is one that compiles via vanilla C only.
3658 By contrast, a registerised build uses the following
3659 architecture-specific hacks for speed:</para>
3663 <para>Global register variables: certain abstract machine
3664 <quote>registers</quote> are mapped to real machine
3665 registers, depending on how many machine registers are
3667 <filename>ghc/includes/MachRegs.h</filename>).</para>
3671 <para>Assembly-mangling: when compiling via C, we feed the
3672 assembly generated by gcc though a Perl script known as the
3673 <firstterm>mangler</firstterm> (see
3674 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3675 mangler rearranges the assembly to support tail-calls and
3676 various other optimisations.</para>
3680 <para>In an unregisterised build, neither of these hacks are
3681 used — the idea is that the C code generated by the
3682 compiler should compile using gcc only. The lack of these
3683 optimisations costs about a factor of two in performance, but
3684 since unregisterised compilation is usually just a step on the
3685 way to a full registerised port, we don't mind too much.</para>
3687 <para>Notes on GHC portability in general: we've tried to stick
3688 to writing portable code in most parts of the system, so it
3689 should compile on any POSIXish system with gcc, but in our
3690 experience most systems differ from the standards in one way or
3691 another. Deal with any problems as they arise - if you get
3692 stuck, ask the experts on
3693 <email>glasgow-haskell-users@haskell.org</email>.</para>
3695 <para>Lots of useful information about the innards of GHC is
3696 available in the <ulink
3697 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3698 Commentary</ulink>, which might be helpful if you run into some
3699 code which needs tweaking for your system.</para>
3702 <title>Cross-compiling to produce an unregisterised GHC</title>
3704 <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
3705 later. If you need instructions for an earlier version of GHC, try
3706 to get hold of the version of this document that was current at the
3707 time. It should be available from the appropriate download page on
3709 url="http://www.haskell.org/ghc/">GHC homepage</ulink>.</para>
3711 <para>In this section, we explain how to bootstrap GHC on a
3712 new platform, using unregisterised intermediate C files. We
3713 haven't put a great deal of effort into automating this
3714 process, for two reasons: it is done very rarely, and the
3715 process usually requires human intervention to cope with minor
3716 porting issues anyway.</para>
3718 <para>The following step-by-step instructions should result in
3719 a fully working, albeit unregisterised, GHC. Firstly, you
3720 need a machine that already has a working GHC (we'll call this
3721 the <firstterm>host</firstterm> machine), in order to
3722 cross-compile the intermediate C files that we will use to
3723 bootstrap the compiler on the <firstterm>target</firstterm>
3728 <para>On the target machine:</para>
3732 <para>Unpack a source tree (preferably a released
3733 version). We will call the path to the root of this
3734 tree <replaceable>T</replaceable>.</para>
3738 <screen>$ cd <replaceable>T</replaceable>
3739 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
3741 <para>You might need to update
3742 <filename>configure.in</filename> to recognise the new
3743 architecture, and re-generate
3744 <filename>configure</filename> with
3745 <literal>autoreconf</literal>.</para>
3749 <screen>$ cd <replaceable>T</replaceable>/ghc/includes
3756 <para>On the host machine:</para>
3760 <para>Unpack a source tree (same released version). Call
3761 this directory <replaceable>H</replaceable>.</para>
3765 <screen>$ cd <replaceable>H</replaceable>
3766 $ ./configure</screen>
3771 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3772 with the following contents:</para>
3774 <programlisting>GhcUnregisterised = YES
3775 GhcLibHcOpts = -O -fvia-C -keep-hc-files
3776 GhcRtsHcOpts = -keep-hc-files
3779 GhcWithNativeCodeGen = NO
3780 GhcWithInterpreter = NO
3781 GhcStage1HcOpts = -O -fasm
3782 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3783 SRC_HC_OPTS += -H32m
3784 GhcBootLibs = YES</programlisting>
3789 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3792 <para>change <literal>TARGETPLATFORM</literal>
3793 appropriately, and set the variables involving
3794 <literal>TARGET</literal> to the correct values for
3795 the target platform. This step is necessary because
3796 currently <literal>configure</literal> doesn't cope
3797 with specifying different values for the
3798 <literal>--host</literal> and
3799 <literal>--target</literal> flags.</para>
3802 <para>copy <literal>LeadingUnderscore</literal>
3803 setting from target.</para>
3810 <filename><replaceable>T</replaceable>/ghc/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/ghc/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/ghc/includes/GHCConstants.h</filename>
3812 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3813 Note that we are building on the host machine, using the
3814 target machine's configuration files. This
3815 is so that the intermediate C files generated here will
3816 be suitable for compiling on the target system.</para>
3820 <para>Touch the generated configuration files, just to make
3821 sure they don't get replaced during the build:</para>
3822 <screen>$ touch <replaceable>H</replaceable>/ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h}</screen>
3826 <para>Now build the compiler:</para>
3827 <screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3828 $ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
3829 <para>Don't worry if the build falls over in the RTS, we
3830 don't need the RTS yet.</para>
3834 <screen>$ cd <replaceable>H</replaceable>/libraries
3835 $ make boot && make</screen>
3839 <screen>$ cd <replaceable>H</replaceable>/ghc/compiler
3840 $ make boot stage=2 && make stage=2</screen>
3844 <screen>$ cd <replaceable>H</replaceable>/ghc/lib
3846 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3847 $ cd <replaceable>H</replaceable>/ghc/utils
3849 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
3853 <screen>$ cd <replaceable>H</replaceable>
3854 $ make hc-file-bundle Project=Ghc</screen>
3859 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3860 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3866 <para>On the target machine:</para>
3868 <para>At this stage we simply need to bootstrap a compiler
3869 from the intermediate C files we generated above. The
3870 process of bootstrapping from C files is automated by the
3871 script in <literal>distrib/hc-build</literal>, and is
3872 described in <xref linkend="sec-booting-from-hc"/>.</para>
3874 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
3876 <para>However, since this is a bootstrap on a new machine,
3877 the automated process might not run to completion the
3878 first time. For that reason, you might want to treat the
3879 <literal>hc-build</literal> script as a list of
3880 instructions to follow, rather than as a fully automated
3881 script. This way you'll be able to restart the process
3882 part-way through if you need to fix anything on the
3885 <para>Don't bother with running
3886 <literal>make install</literal> in the newly
3887 bootstrapped tree; just use the compiler in that tree to
3888 build a fresh compiler from scratch, this time without
3889 booting from C files. Before doing this, you might want
3890 to check that the bootstrapped compiler is generating
3891 working binaries:</para>
3893 <screen>$ cat >hello.hs
3894 main = putStrLn "Hello World!\n"
3896 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3898 Hello World!</screen>
3900 <para>Once you have the unregisterised compiler up and
3901 running, you can use it to start a registerised port. The
3902 following sections describe the various parts of the
3903 system that will need architecture-specific tweaks in
3904 order to get a registerised build going.</para>
3911 <title>Porting the RTS</title>
3913 <para>The following files need architecture-specific code for a
3914 registerised build:</para>
3918 <term><filename>ghc/includes/MachRegs.h</filename>
3919 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
3922 <para>Defines the STG-register to machine-register
3923 mapping. You need to know your platform's C calling
3924 convention, and which registers are generally available
3925 for mapping to global register variables. There are
3926 plenty of useful comments in this file.</para>
3930 <term><filename>ghc/includes/TailCalls.h</filename>
3931 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
3934 <para>Macros that cooperate with the mangler (see <xref
3935 linkend="sec-mangler"/>) to make proper tail-calls
3940 <term><filename>ghc/rts/Adjustor.c</filename>
3941 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
3945 <literal>foreign import "wrapper"</literal>
3947 <literal>foreign export dynamic</literal>).
3948 Not essential for getting GHC bootstrapped, so this file
3949 can be deferred until later if necessary.</para>
3953 <term><filename>ghc/rts/StgCRun.c</filename>
3954 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
3957 <para>The little assembly layer between the C world and
3958 the Haskell world. See the comments and code for the
3959 other architectures in this file for pointers.</para>
3963 <term><filename>ghc/rts/MBlock.h</filename>
3964 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
3966 <term><filename>ghc/rts/MBlock.c</filename>
3967 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
3970 <para>These files are really OS-specific rather than
3971 architecture-specific. In <filename>MBlock.h</filename>
3972 is specified the absolute location at which the RTS
3973 should try to allocate memory on your platform (try to
3974 find an area which doesn't conflict with code or dynamic
3975 libraries). In <filename>Mblock.c</filename> you might
3976 need to tweak the call to <literal>mmap()</literal> for
3983 <sect3 id="sec-mangler">
3984 <title>The mangler</title>
3986 <para>The mangler is an evil Perl-script
3987 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
3988 rearranges the assembly code output from gcc to do two main
3993 <para>Remove function prologues and epilogues, and all
3994 movement of the C stack pointer. This is to support
3995 tail-calls: every code block in Haskell code ends in an
3996 explicit jump, so we don't want the C-stack overflowing
3997 while we're jumping around between code blocks.</para>
4000 <para>Move the <firstterm>info table</firstterm> for a
4001 closure next to the entry code for that closure. In
4002 unregisterised code, info tables contain a pointer to the
4003 entry code, but in registerised compilation we arrange
4004 that the info table is shoved right up against the entry
4005 code, and addressed backwards from the entry code pointer
4006 (this saves a word in the info table and an extra
4007 indirection when jumping to the closure entry
4012 <para>The mangler is abstracted to a certain extent over some
4013 architecture-specific things such as the particular assembler
4014 directives used to herald symbols. Take a look at the
4015 definitions for other architectures and use these as a
4016 starting point.</para>
4020 <title>The splitter</title>
4022 <para>The splitter is another evil Perl script
4023 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
4024 cooperates with the mangler to support object splitting.
4025 Object splitting is what happens when the
4026 <option>-split-objs</option> option is passed to GHC: the
4027 object file is split into many smaller objects. This feature
4028 is used when building libraries, so that a program statically
4029 linked against the library will pull in less of the
4032 <para>The splitter has some platform-specific stuff; take a
4033 look and tweak it for your system.</para>
4037 <title>The native code generator</title>
4039 <para>The native code generator isn't essential to getting a
4040 registerised build going, but it's a desirable thing to have
4041 because it can cut compilation times in half. The native code
4042 generator is described in some detail in the <ulink
4043 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
4044 commentary</ulink>.</para>
4050 <para>To support GHCi, you need to port the dynamic linker
4051 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
4052 currently supports the ELF and PEi386 object file formats - if
4053 your platform uses one of these then things will be
4054 significantly easier. The majority of Unix platforms use the
4055 ELF format these days. Even so, there are some
4056 machine-specific parts of the ELF linker: for example, the
4057 code for resolving particular relocation types is
4058 machine-specific, so some porting of this code to your
4059 architecture will probaly be necessary.</para>
4061 <para>If your system uses a different object file format, then
4062 you have to write a linker — good luck!</para>
4068 <sect1 id="sec-build-pitfalls">
4069 <title>Known pitfalls in building Glasgow Haskell
4071 <indexterm><primary>problems, building</primary></indexterm>
4072 <indexterm><primary>pitfalls, in building</primary></indexterm>
4073 <indexterm><primary>building pitfalls</primary></indexterm></title>
4076 WARNINGS about pitfalls and known “problems”:
4085 One difficulty that comes up from time to time is running out of space
4086 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
4087 compensate for the vagaries of different sysadmin approaches to temp
4089 <indexterm><primary>tmp, running out of space in</primary></indexterm>
4091 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
4092 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
4095 The best way around it is to say
4097 <programlisting>export TMPDIR=<dir></programlisting>
4099 in your <filename>build.mk</filename> file.
4100 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
4109 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
4110 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
4118 When compiling via C, you'll sometimes get “warning: assignment from
4119 incompatible pointer type” out of GCC. Harmless.
4126 Similarly, <command>ar</command>chiving warning messages like the following are not
4129 <screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
4130 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
4139 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
4140 get an “Out of heap space” error message. These can vary with the
4141 vagaries of different systems, it seems. The solution is simple:
4148 If you're compiling with GHC 4.00 or later, then the
4149 <emphasis>maximum</emphasis> heap size must have been reached. This
4150 is somewhat unlikely, since the maximum is set to 64M by default.
4151 Anyway, you can raise it with the
4152 <option>-optCrts-M<size></option> flag (add this flag to
4153 <constant><module>_HC_OPTS</constant>
4154 <command>make</command> variable in the appropriate
4155 <filename>Makefile</filename>).
4162 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4171 and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
4172 <constant><module>_HC_OPTS</constant>.)
4174 Alternatively, just cut to the chase:
4176 <screen>$ cd ghc/compiler
4177 $ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
4185 If you try to compile some Haskell, and you get errors from GCC about
4186 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4187 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4189 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4190 this bug also suggests that you have an old GCC.
4198 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4201 <screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4202 $ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4204 ? # or, on some machines: ar s $i
4208 We'd be interested to know if this is still necessary.
4216 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4217 a bit from one Unix to another. One particular gotcha is macro calls
4221 <programlisting>SLIT("Hello, world")</programlisting>
4224 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4225 arguments, so you get
4228 <screen>:731: macro `SLIT' used with too many (2) args</screen>
4231 Alas, <command>cpp</command> doesn't tell you the offending file!
4233 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4244 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
4246 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
4247 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
4250 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
4252 <para> The build system is built around Unix-y makefiles. Because it's not native,
4253 the Windows situation for building GHC is particularly confusing. This section
4254 tries to clarify, and to establish terminology.</para>
4256 <sect3 id="ghc-mingw"><title>MinGW</title>
4258 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4259 is a collection of header
4260 files and import libraries that allow one to use <command>gcc</command> and produce
4261 native Win32 programs that do not rely on any third-party DLLs. The
4262 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4263 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4267 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
4272 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
4274 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
4275 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
4276 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
4277 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
4278 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
4282 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
4283 compile code that has access to all of Posix. The price is that the executables must be
4284 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
4285 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4286 does not change, but the implementation certainly does. Even the interfaces to functions
4287 it exports seem to change occasionally. </para>
4291 MSYS is a fork of the Cygwin tree, so they
4292 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
4293 through fewer layers, so MSYS is quite a bit faster too.
4296 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
4297 compile binaries that run with no DLL support, on any Win32 system.
4298 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
4299 <command>cvs</command>, <command>ssh</command> etc. To get these, you have to download the
4300 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
4302 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
4303 <command>ssh</command> and so on),
4304 not by programs compiled under MSYS.
4312 <sect3><title>Targeting MinGW</title>
4314 <para>We want GHC to compile programs that work on any Win32 system. Hence:
4317 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
4318 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
4319 will work on any system, but it also means that the programs GHC compiles do not have access
4320 to all of Posix. In particular, they cannot import the (Haskell) Posix
4321 library; they have to do
4322 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
4323 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4327 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
4328 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4331 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
4332 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
4333 that targets Cygwin instead. The up-side of GHC-cygwin is
4334 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4335 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
4338 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
4339 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
4340 GHC; both work fine, though MSYS is rather lighter weight.</para>
4342 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
4343 uses the <command>gcc</command> that you specify using the
4344 <option>--with-gcc</option> flag when you run
4345 <command>configure</command> (see below).
4346 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
4347 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
4348 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
4349 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
4350 used to glom together .o files into a bigger .o file, or a .a file,
4351 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4352 Cygwin and MinGW use the same .o file format. So its ok.
4356 <sect3><title> File names </title>
4358 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
4362 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
4363 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
4365 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
4366 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
4367 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
4369 <programlisting>foogle -B/c/tmp/baz</programlisting>
4370 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
4374 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
4376 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
4382 <sect3><title>Crippled <command>ld</command></title>
4385 It turns out that on both Cygwin and MSYS, the <command>ld</command> has a
4386 limit of 32kbytes on its command line. Especially when using split object
4387 files, the make system can emit calls to <command>ld</command> with thousands
4388 of files on it. Then you may see something like this:
4390 (cd Graphics/Rendering/OpenGL/GL/QueryUtils_split && /mingw/bin/ld -r -x -o ../QueryUtils.o *.o)
4391 /bin/sh: /mingw/bin/ld: Invalid argument
4393 The solution is either to switch off object file splitting (set
4394 <option>SplitObjs</option> to <literal>NO</literal> in your
4395 <filename>build.mk</filename>),
4396 or to make the module smaller.
4400 <sect3><title>Host System vs Target System</title>
4403 In the source code you'll find various ifdefs looking like:
4404 <programlisting>#ifdef mingw32_HOST_OS
4406 #endif</programlisting>
4408 <programlisting>#ifdef mingw32_TARGET_OS
4410 #endif</programlisting>
4411 These macros are set by the configure script (via the file config.h).
4412 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4415 <para>The "host" system is the one on which GHC itself will be run.</para>
4418 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
4421 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4422 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4429 <sect2><title>Wrapper scripts</title>
4432 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
4433 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
4434 GHC itself as an example:
4437 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
4438 paths to the front of the source file <filename>ghc.sh</filename>,
4439 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
4440 where to find its supporting files.
4444 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
4445 native Windows shell <command>cmd</command> (e.g. limits on the length
4446 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
4447 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
4448 and from that figures out where the supporting files are.
4451 (You can find the layout of GHC's supporting files in the
4452 section "Layout of installed files" of Section 2 of the GHC user guide.)
4455 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
4456 execute a program that has just been built in a build tree. The difference is that the
4457 layout of the supporting files is different.
4458 In this case, whether on Windows or Unix, we always use a shell script. This works OK
4459 on Windows because the script is executed by MSYS or Cygwin, which don't have the
4460 shortcomings of the native Windows <command>cmd</command> shell.
4467 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
4470 This section gives detailed instructions for how to build
4471 GHC from source on your Windows machine. Similar instructions for
4472 installing and running GHC may be found in the user guide. In general,
4473 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4476 Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
4477 before reading section.
4478 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
4479 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
4482 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
4485 MSYS is a lightweight alternative to Cygwin.
4486 You don't need MSYS to <emphasis>use</emphasis> GHC,
4487 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
4488 Here's how to install MSYS.
4491 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
4492 download the following (of course, the version numbers will differ):
4494 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
4496 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
4497 This provides <command>make</command>, <command>autoconf</command>,
4498 <command>ssh</command>, <command>cvs</command> and probably more besides.
4501 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
4505 Set the following environment variables
4507 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> and
4508 <literal>c:/msys/1.0/local/bin</literal>
4509 to your path. (Of course, the version number may differ.)
4510 MSYS mounts the former as both <literal>/bin</literal> and
4511 <literal>/usr/bin</literal> and the latter as <literal>/usr/local/bin</literal>.
4514 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
4515 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
4518 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
4521 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
4525 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
4532 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
4533 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
4534 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
4535 file has too-liberal permissinos.
4540 <para>Here are some points to bear in mind when using MSYS:
4542 <listitem> <para> MSYS does some kind of special magic to binaries stored in
4543 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
4544 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
4545 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
4546 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
4547 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
4549 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
4553 Win32 has a <command>find</command> command which is not the same as MSYS's find.
4554 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4555 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4556 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4557 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4561 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
4562 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
4563 bzip'd dump.</para></listitem>
4569 <sect2><title>Installing and configuring Cygwin</title>
4571 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4572 The installation process is straightforward; we install it in <filename>c:/cygwin</filename>.
4573 During the installation dialogue, make sure that you select all of the following:
4574 <command>cvs</command>,
4575 <command>openssh</command>,
4576 <command>autoconf</command>,
4577 <command>binutils</command> (includes ld and (I think) ar),
4578 <command>gcc</command>,
4579 <command>flex</command>,
4580 <command>make</command>.
4581 If you miss out any of these, strange things will happen to you. To see thse packages,
4582 click on the "View" button in the "Select Packages"
4583 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
4584 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
4586 <para> Now set the following user environment variables:
4589 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4590 <constant>PATH</constant></para></listitem>
4594 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
4595 don't do this you get very weird messages when you type
4596 <command>make</command>, such as:
4597 <screen>/c: /c: No such file or directory</screen>
4601 <listitem><para> Set <constant>SHELL</constant> to
4602 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
4603 <constant>SHELL</constant> is what you get.
4606 <listitem><para> Set <constant>HOME</constant> to point to your
4607 home directory. This is where, for example,
4608 <command>bash</command> will look for your <filename>.bashrc</filename>
4609 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4615 There are a few other things to do:
4619 By default, cygwin provides the command shell <filename>ash</filename>
4620 as <filename>sh.exe</filename>. We have often seen build-system problems that
4621 turn out to be due to bugs in <filename>ash</filename>
4623 and length of command lines). On the other hand <filename>bash</filename> seems
4625 So, in <filename>cygwin/bin</filename>
4626 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4627 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4628 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4629 you can't rename a running program!
4635 Some script files used in the make system start with "<command>#!/bin/perl</command>",
4636 (and similarly for <command>sh</command>). Notice the hardwired path!
4637 So you need to ensure that your <filename>/bin</filename> directory has the following
4640 <listitem> <para><command>sh</command></para></listitem>
4641 <listitem> <para><command>perl</command></para></listitem>
4642 <listitem> <para><command>cat</command></para></listitem>
4644 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
4645 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
4646 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
4647 (You can discover where your Cygwin
4648 root directory <filename>/</filename> is by typing <command>mount</command>.)
4649 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
4650 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4651 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4657 <para>Finally, here are some things to be aware of when using Cygwin:
4659 <listitem> <para>Cygwin doesn't deal well with filenames that include
4660 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4664 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4665 magical text in it. So other programs that don't use Cygwin's
4666 I/O libraries won't recognise such files as symlinks.
4667 In particular, programs compiled by GHC are meant to be runnable
4668 without having Cygwin, so they don't use the Cygwin library, so
4669 they don't recognise symlinks.
4673 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
4674 which apply to Cygwin too.
4682 <sect2 id="configure-ssh"><title>Configuring SSH</title>
4684 <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
4685 you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
4686 (not ssh) in the Cygwin list of applications!</para>
4688 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
4692 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
4693 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
4694 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
4695 and run it as follows:
4696 <screen>c:\tmp> set CYGWIN32=tty
4697 c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
4700 <listitem><para> (Cygwin-only problem, I think.)
4701 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
4702 To determine your home directory <command>ssh</command> first looks in
4703 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
4704 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
4705 the setting of the environment variable $HOME</emphasis>. If the home directory is
4706 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
4707 <screen>ssh -v cvs.haskell.org</screen>
4708 which makes <command>ssh</command> print out information about its activity.
4710 <para> You can fix this problem, either by correcting the home-directory field in
4711 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
4712 you do that, <command>ssh</command> uses the $HOME environment variable instead.
4718 <para>To protect your
4719 <literal>.ssh</literal> from access by anyone else,
4720 right-click your <literal>.ssh</literal> directory, and
4721 select <literal>Properties</literal>. If you are not on
4722 the access control list, add yourself, and give yourself
4723 full permissions (the second panel). Remove everyone else
4724 from the access control list. Don't leave them there but
4725 deny them access, because 'they' may be a list that
4726 includes you!</para>
4730 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4731 you to have Unix permissions 600 (read/write for owner only)
4732 on the <literal>.ssh/identity</literal> file, else it
4733 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4734 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4735 The solution seems to be to set the $CYGWIN environment
4736 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4737 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4738 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4745 <sect2><title>Other things you need to install</title>
4747 <para>You have to install the following other things to build GHC, listed below.</para>
4749 <para>On Windows you often install executables in directories with spaces, such as
4750 "<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
4751 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
4752 to put binaries for all tools in places with no spaces in their path.
4753 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
4754 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
4755 provided they are in your path.
4759 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4760 This is what you will use to compile GHC. Add it in your
4761 <constant>PATH</constant>: the installer tells you the path element
4762 you need to add upon completion.
4768 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4769 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
4770 build it from the source distribution using
4771 <screen>$ ./configure
4773 $ make install</screen>
4774 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
4776 Make sure the installation directory is in your
4777 <constant>PATH</constant>.
4782 <para>Install an executable Alex. This can be done by building from the
4783 source distribution in the same way as Happy. Sources are
4784 available from <ulink
4785 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4789 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4790 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
4791 Just pick up a mingw bundle at
4792 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4793 We install it in <filename>c:/mingw</filename>.
4796 <para><emphasis>On MSYS</emphasis>, add <literal>c:/mingw/bin</literal> to your PATH. MSYS does not provide <command>gcc</command>,
4797 <command>ld</command>, <command>ar</command>, and so on, because it just uses the MinGW ones. So you need them
4801 <para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4802 They are only going to get used by explicit access (via the --with-gcc flag you
4803 give to <command>configure</command> later). If you do add them to your path
4804 you are likely to get into a mess because their names overlap with Cygwin binaries.
4810 <para>We use <command>emacs</command> a lot, so we install that too.
4811 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4812 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4813 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4814 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4815 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4816 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4821 <para>You might want to install GLUT in your MSYS/Cygwin
4822 installation, otherwise the GLUT package will not be built with
4827 <para> Finally, check out a copy of GHC sources from
4828 the CVS repository, following the instructions above (<xref linkend="cvs-access"/>).
4835 <sect2><title>Building GHC</title>
4838 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
4839 the bullets below only tell
4840 you about Windows-specific wrinkles.</para>
4844 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
4845 you'll get an error when you run <filename>./configure</filename>:
4848 creating mk/config.h
4849 mk/config.h is unchanged
4851 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4852 ./configure: ./configure: No such file or directory
4853 configure: error: ./configure failed for ghc</screen>
4857 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
4858 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
4860 <screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
4861 Solution: delete <filename>configure</filename> first.
4866 After <command>autoreconf</command> run <command>./configure</command> in
4867 <filename>fptools/</filename> thus:
4869 <screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
4870 This is the point at which you specify that you are building GHC-mingw
4871 (see <xref linkend="ghc-mingw"/>). </para>
4873 <para> Both these options are important! It's possible to get into
4874 trouble using the wrong C compiler!</para>
4876 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4877 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4878 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4879 understand a Cygwin path. For example, if you
4880 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4881 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4882 time it tries to invoke it. Worse, the failure comes with
4883 no error message whatsoever. GHC simply fails silently when first invoked,
4884 typically leaving you with this:
4885 <screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4886 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4887 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4888 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4889 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4890 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4891 -optc-fomit-frame-pointer -O2 -static
4892 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4893 make[2]: *** [Adjustor.o] Error 1
4894 make[1]: *** [all] Error 1
4895 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4896 make: *** [all] Error 1</screen>
4901 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
4902 you'll have to do something more like:
4903 <screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
4908 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4909 This file occasionally remembers out-of-date configuration information, which
4910 can be really confusing.
4914 <listitem><para> You almost certainly want to set
4915 <programlisting>SplitObjs = NO</programlisting>
4916 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
4917 This tells the build system not to split each library into a myriad of little object files, one
4918 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4919 it dramatically increases the time taken to build the libraries in the first place.
4923 <listitem><para> Do not attempt to build the documentation.
4924 It needs all kinds of wierd Jade stuff that we haven't worked out for
4925 Win32.</para></listitem>
projects / ghc-hetmet.git / blob