1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
3 <Article id="building-guide">
7 <Title>Building the Glasgow Functional Programming Tools Suite</Title>
8 <Author><OtherName>The GHC Team</OtherName></Author>
9 <Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
10 <PubDate>November 2001</PubDate>
13 <para>The Glasgow fptools suite is a collection of Functional
14 Programming related tools, including the Glasgow Haskell
15 Compiler (GHC). The source code for the whole suite is kept in
16 a single CVS repository and shares a common build and
17 installation system.</para>
19 <para>This guide is intended for people who want to build or
20 modify programs from the Glasgow <Literal>fptools</Literal>
21 suite (as distinct from those who merely want to
22 <Emphasis>run</Emphasis> them). Installation instructions are
23 now provided in the user guide.</para>
25 <para>The bulk of this guide applies to building on Unix
26 systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
32 <sect1 id="sec-getting">
33 <title>Getting the sources</title>
35 <para>You can get your hands on the <literal>fptools</literal>
41 <term><indexterm><primary>Source
42 distributions</primary></indexterm>Source distributions</term>
44 <para>You have a supported platform, but (a) you like
45 the warm fuzzy feeling of compiling things yourself;
46 (b) you want to build something ``extra”—e.g., a
47 set of libraries with strictness-analysis turned off; or
48 (c) you want to hack on GHC yourself.</para>
50 <para>A source distribution contains complete sources for
51 one or more projects in the <literal>fptools</literal>
52 suite. Not only that, but the more awkward
53 machine-independent steps are done for you. For example, if
55 <command>happy</command><indexterm><primary>happy</primary></indexterm>
56 you'll find it convenient that the source distribution
57 contains the result of running <command>happy</command> on
58 the parser specifications. If you don't want to alter the
59 parser then this saves you having to find and install
60 <command>happy</command>. You will still need a working
61 version of GHC (preferably version 4.08+) on your machine in
62 order to compile (most of) the sources, however.</para>
67 <term>The CVS repository.</term>
68 <indexterm><primary>CVS repository</primary>
71 <para>We make releases infrequently. If you want more
72 up-to-the minute (but less tested) source code then you need
73 to get access to our CVS repository.</para>
75 <para>All the <literal>fptools</literal> source code is held
76 in a CVS repository. CVS is a pretty good source-code
77 control system, and best of all it works over the
80 <para>The repository holds source code only. It holds no
81 mechanically generated files at all. So if you check out a
82 source tree from CVS you will need to install every utility
83 so that you can build all the derived files from
86 <para>More information about our CVS repository can be found
87 in <xref linkend="sec-cvs">.</para>
92 <para>If you are going to do any building from sources (either
93 from a source distribution or the CVS repository) then you need to
94 read all of this manual in detail.</para>
98 <title>Using the CVS repository</title>
100 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
101 sources for various software projects. CVS lets several people
102 work on the same software at the same time, allowing changes to be
103 checked in incrementally. </para>
105 <para>This section is a set of guidelines for how to use our CVS
106 repository, and will probably evolve in time. The main thing to
107 remember is that most mistakes can be undone, but if there's
108 anything you're not sure about feel free to bug the local CVS
109 meister (namely Jeff Lewis
110 <email>jlewis@galconn.com</email>). </para>
112 <sect2 id="cvs-access">
113 <title>Getting access to the CVS Repository</title>
115 <para>You can access the repository in one of two ways:
116 read-only (<xref linkend="cvs-read-only">), or read-write (<xref
117 linkend="cvs-read-write">).</para>
119 <sect3 id="cvs-read-only">
120 <title>Remote Read-only CVS Access</title>
122 <para>Read-only access is available to anyone - there's no
123 need to ask us first. With read-only CVS access you can do
124 anything except commit changes to the repository. You can
125 make changes to your local tree, and still use CVS's merge
126 facility to keep your tree up to date, and you can generate
127 patches using 'cvs diff' in order to send to us for
130 <para>To get read-only access to the repository:</para>
134 <para>Make sure that <application>cvs</application> is
135 installed on your machine.</para>
138 <para>Set your <literal>$CVSROOT</literal> environment variable to
139 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
142 <para>Run the command</para>
146 <para>The password is simply <literal>cvs</literal>. This
147 sets up a file in your home directory called
148 <literal>.cvspass</literal>, which squirrels away the
149 dummy password, so you only need to do this step once.</para>
153 <para>Now go to <xref linkend="cvs-first">.</para>
158 <sect3 id="cvs-read-write">
159 <title>Remote Read-Write CVS Access</title>
161 <para>We generally supply read-write access to folk doing
162 serious development on some part of the source tree, when
163 going through us would be a pain. If you're developing some
164 feature, or think you have the time and inclination to fix
165 bugs in our sources, feel free to ask for read-write
166 access. There is a certain amount of responsibility that goes
167 with commit privileges; we are more likely to grant you access
168 if you've demonstrated your competence by sending us patches
169 via mail in the past.</para>
171 <para>To get remote read-write CVS access, you need to do the
172 following steps.</para>
176 <para>Make sure that <literal>cvs</literal> and
177 <literal>ssh</literal> are both installed on your
182 <para>Generate a DSA private-key/public-key pair, thus:</para>
186 <para>(<literal>ssh-keygen</literal> comes with
187 <literal>ssh</literal>.) Running <literal>ssh-keygen
188 -d</literal> creates the private and public keys in
189 <literal>$HOME/.ssh/id_dsa</literal> and
190 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
191 (assuming you accept the standard defaults).</para>
193 <para><literal>ssh-keygen -d</literal> will only work if
194 you have Version 2 <literal>ssh</literal> installed; it
195 will fail harmlessly otherwise. If you only have Version
196 1 you can instead generate an RSA key pair using plain</para>
201 <para>Doing so creates the private and public RSA keys in
202 <literal>$HOME/.ssh/identity</literal> and
203 <literal>$HOME/.ssh/identity.pub</literal>
206 <para>[Deprecated.] Incidentally, you can force a Version
207 2 <literal>ssh</literal> to use the Version 1 protocol by
208 creating <literal>$HOME/config</literal> with the
209 following in it:</para>
217 <para>In both cases, <literal>ssh-keygen</literal> will
218 ask for a <firstterm>passphrase</firstterm>. The
219 passphrase is a password that protects your private key.
220 In response to the 'Enter passphrase' question, you can
224 <para>[Recommended.] Enter a passphrase, which you
225 will quote each time you use CVS.
226 <literal>ssh-agent</literal> makes this entirely
230 <para>[Deprecated.] Just hit return (i.e. use an empty
231 passphrase); then you won't need to quote the
232 passphrase when using CVS. The downside is that
233 anyone who can see into your <literal>.ssh</literal>
234 directory, and thereby get your private key, can mess
235 up the repository. So you must keep the
236 <literal>.ssh</literal> directory with draconian
237 no-access permissions.</para>
243 [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
244 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
245 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
246 and run it as follows:
248 c:\tmp> set CYGWIN32=tty
249 c:\tmp> c:/user/local/bin/ssh-keygen1
252 <para>[Windows users.] To protect your
253 <literal>.ssh</literal> from access by anyone else,
254 right-click your <literal>.ssh</literal> directory, and
255 select <literal>Properties</literal>. If you are not on
256 the access control list, add yourself, and give yourself
257 full permissions (the second panel). Remove everyone else
258 from the access control list. Don't leave them there but
259 deny them access, because 'they' may be a list that
264 <para>Send a message to to the CVS repository
265 administrator (currently Jeff Lewis
266 <email>jeff@galconn.com</email>), containing:</para>
269 <para>Your desired user-name.</para>
272 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
273 <literal>.ssh/identity.pub</literal>).</para>
276 <para>He will set up your account.</para>
280 <para>Set the following environment variables:</para>
284 <constant>$HOME</constant>: points to your home directory. This is where CVS
285 will look for its <filename>.cvsrc</filename> file.
291 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
293 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
294 <literal>ssh</literal> assumes that your CVS client
295 understands how to execute shell script
296 ("#!"s,really), which is what
297 <literal>ssh</literal> is. This may not be the case on
298 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
299 <literal>ssh1</literal>.</para>
303 <para><literal>$CVSROOT</literal> to
304 <literal>:ext:</literal><replaceable>your-username</replaceable>
305 <literal>@cvs.haskell.org:/home/cvs/root</literal>
306 where <replaceable>your-username</replaceable> is your user name on
307 <literal>cvs.haskell.org</literal>.
309 <para>The <literal>CVSROOT</literal> environment variable will
310 be recorded in the checked-out tree, so you don't need to set
311 this every time. </para>
317 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
318 if you want to use an Emacs buffer for typing in those long commit messages.
324 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
325 set this to point to <filename>bash.exe</filename>.
336 Put the following in <filename>$HOME/.cvsrc</filename>:
347 These are the default options for the specified CVS commands,
348 and represent better defaults than the usual ones. (Feel
349 free to change them.)
353 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
354 the 8.3 DOS filesystem, but that restriction should have
355 been lifted by now (i.e., you're using VFAT or later filesystems.) If
356 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
364 <para>[Experts.] Once your account is set up, you can get
365 access from other machines without bothering Jeff, thus:</para>
368 <para>Generate a public/private key pair on the new
372 <para>Use ssh to log in to
373 <literal>cvs.haskell.org</literal>, from your old
377 <para>Add the public key for the new machine to the file
378 <literal>$HOME/ssh/authorized_keys</literal> on
379 <literal>cvs.haskell.org</literal>.
380 (<literal>authorized_keys2</literal>, I think, for Version
384 <para>Make sure that the new version of
385 <literal>authorized_keys</literal> still has 600 file
394 <sect2 id="cvs-first">
395 <title>Checking Out a Source Tree</title>
399 <para>Make sure you set your <literal>CVSROOT</literal>
400 environment variable according to either of the remote
401 methods above. The Approved Way to check out a source tree
402 is as follows:</para>
405 $ cvs checkout fpconfig
408 <para>At this point you have a new directory called
409 <literal>fptools</literal> which contains the basic stuff
410 for the fptools suite, including the configuration files and
411 some other junk. </para>
413 <para>[Windows users.] The following messages appear to be harmless:
415 setsockopt IPTOS_LOWDELAY: Invalid argument
416 setsockopt IPTOS_THROUGHPUT: Invalid argument
421 <para>You can call the fptools directory whatever you like,
422 CVS won't mind: </para>
425 $ mv fptools <replaceable>directory</replaceable>
428 <para> NB: after you've read the CVS manual you might be
429 tempted to try</para>
431 $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
434 <para>instead of checking out <literal>fpconfig</literal>
435 and then renaming it. But this doesn't work, and will
436 result in checking out the entire repository instead of just
437 the <literal>fpconfig</literal> bit.</para>
439 $ cd <replaceable>directory</replaceable>
440 $ cvs checkout ghc hslibs
443 <para>The second command here checks out the relevant
444 modules you want to work on. For a GHC build, for instance,
445 you need at least the <literal>ghc</literal> and
446 <literal>hslibs</literal> modules (for a full list of the
447 projects available, see <xref linkend="projects">).</para>
452 <sect2 id="cvs-committing">
453 <title>Committing Changes</title>
455 <para>This is only if you have read-write access to the
456 repository. For anoncvs users, CVS will issue a "read-only
457 repository" error if you try to commit changes.</para>
461 <para>Build the software, if necessary. Unless you're just
462 working on documentation, you'll probably want to build the
463 software in order to test any changes you make.</para>
467 <para>Make changes. Preferably small ones first.</para>
471 <para>Test them. You can see exactly what changes you've
472 made by using the <literal>cvs diff</literal> command:</para>
476 <para>lists all the changes (using the
477 <literal>diff</literal> command) in and below the current
478 directory. In emacs, <literal>C-c C-v =</literal> runs
479 <literal>cvs diff</literal> on the current buffer and shows
480 you the results.</para>
484 <para>Before checking in a change, you need to update your
491 <para>This pulls in any changes that other people have made,
492 and merges them with yours. If there are any conflicts, CVS
493 will tell you, and you'll have to resolve them before you
494 can check your changes in. The documentation describes what
495 to do in the event of a conflict.</para>
497 <para>It's not always necessary to do a full cvs update
498 before checking in a change, since CVS will always tell you
499 if you try to check in a file that someone else has changed.
500 However, you should still update at regular intervals to
501 avoid making changes that don't work in conjuction with
502 changes that someone else made. Keeping an eye on what goes
503 by on the mailing list can help here.</para>
507 <para>When you're happy that your change isn't going to
508 break anything, check it in. For a one-file change:</para>
511 $ cvs commit <replaceable>filename</replaceable>
514 <para>CVS will then pop up an editor for you to enter a
515 "commit message", this is just a short description
516 of what your change does, and will be kept in the history of
519 <para>If you're using emacs, simply load up the file into a
520 buffer and type <literal>C-x C-q</literal>, and emacs will
521 prompt for a commit message and then check in the file for
524 <para>For a multiple-file change, things are a bit
525 trickier. There are several ways to do this, but this is the
526 way I find easiest. First type the commit message into a
527 temporary file. Then either</para>
530 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
533 <para>or, if nothing else has changed in this part of the
537 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
540 <para>where <replaceable>directory</replaceable> is a common
541 parent directory for all your changes, and
542 <replaceable>commit-message</replaceable> is the name of the
543 file containing the commit message.</para>
545 <para>Shortly afterwards, you'll get some mail from the
546 relevant mailing list saying which files changed, and giving
547 the commit message. For a multiple-file change, you should
548 still get only <emphasis>one</emphasis> message.</para>
553 <sect2 id="cvs-update">
554 <title>Updating Your Source Tree</title>
556 <para>It can be tempting to cvs update just part of a source
557 tree to bring in some changes that someone else has made, or
558 before committing your own changes. This is NOT RECOMMENDED!
559 Quite often changes in one part of the tree are dependent on
560 changes in another part of the tree (the
561 <literal>mk/*.mk</literal> files are a good example where
562 problems crop up quite often). Having an inconsistent tree is a
563 major cause of headaches. </para>
565 <para>So, to avoid a lot of hassle, follow this recipe for
566 updating your tree: </para>
570 $ cvs update -Pd 2>&1 | tee log</screen>
572 <para>Look at the log file, and fix any conflicts (denoted by a
573 <quote>C</quote> in the first column). If you're using multiple
574 build trees, then for every build tree you have pointing at this
575 source tree, you need to update the links in case any new files
576 have appeared: </para>
579 $ cd <replaceable>build-tree</replaceable>
580 $ lndir <replaceable>source-tree</replaceable>
583 <para>Some files might have been removed, so you need to remove
584 the links pointing to these non-existent files:</para>
587 $ find . -xtype l -exec rm '{}' \;
590 <para>To be <emphasis>really</emphasis> safe, you should do
593 <screen>$ gmake all</screen>
595 <para>from the top-level, to update the dependencies and build
596 any changed files. </para>
599 <sect2 id="cvs-tags">
600 <title>GHC Tag Policy</title>
602 <para>If you want to check out a particular version of GHC,
603 you'll need to know how we tag versions in the repository. The
604 policy (as of 4.04) is:</para>
608 <para>The tree is branched before every major release. The
609 branch tag is <literal>ghc-x-xx-branch</literal>, where
610 <literal>x-xx</literal> is the version number of the release
611 with the <literal>'.'</literal> replaced by a
612 <literal>'-'</literal>. For example, the 4.04 release lives
613 on <literal>ghc-4-04-branch</literal>.</para>
617 <para>The release itself is tagged with
618 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
619 called <literal>ghc-4-06</literal>.</para>
623 <para>We didn't always follow these guidelines, so to see
624 what tags there are for previous versions, do <literal>cvs
625 log</literal> on a file that's been around for a while (like
626 <literal>fptools/ghc/README</literal>).</para>
630 <para>So, to check out a fresh GHC 4.06 tree you would
634 $ cvs co -r ghc-4-06 fpconfig
636 $ cvs co -r ghc-4-06 ghc hslibs
640 <sect2 id="cvs-hints">
641 <title>General Hints</title>
645 <para>As a general rule: commit changes in small units,
646 preferably addressing one issue or implementing a single
647 feature. Provide a descriptive log message so that the
648 repository records exactly which changes were required to
649 implement a given feature/fix a bug. I've found this
650 <emphasis>very</emphasis> useful in the past for finding out
651 when a particular bug was introduced: you can just wind back
652 the CVS tree until the bug disappears.</para>
656 <para>Keep the sources at least *buildable* at any given
657 time. No doubt bugs will creep in, but it's quite easy to
658 ensure that any change made at least leaves the tree in a
659 buildable state. We do nightly builds of GHC to keep an eye
660 on what things work/don't work each day and how we're doing
661 in relation to previous verions. This idea is truely wrecked
662 if the compiler won't build in the first place!</para>
666 <para>To check out extra bits into an already-checked-out
667 tree, use the following procedure. Suppose you have a
668 checked-out fptools tree containing just ghc, and you want
669 to add nofib to it:</para>
680 $ cvs update -d nofib
683 <para>(the -d flag tells update to create a new
684 directory). If you just want part of the nofib suite, you
689 $ cvs checkout nofib/spectral
692 <para>This works because <literal>nofib</literal> is a
693 module in its own right, and spectral is a subdirectory of
694 the nofib module. The path argument to checkout must always
695 start with a module name. There's no equivalent form of this
696 command using <literal>update</literal>.</para>
702 <sect1 id="projects">
703 <title>What projects are there?</title>
705 <para>The <literal>fptools</literal> suite consists of several
706 <firstterm>projects</firstterm>, most of which can be downloaded,
707 built and installed individually. Each project corresponds to a
708 subdirectory in the source tree, and if checking out from CVS then
709 each project can be checked out individually by sitting in the top
710 level of your source tree and typing <command>cvs checkout
711 <replaceable>project</replaceable></command>.</para>
713 <para>Here is a list of the projects currently available:</para>
717 <term><literal>ghc</literal></term>
718 <indexterm><primary><literal>ghc</literal></primary>
719 <secondary>project</secondary></indexterm>
721 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
722 Haskell Compiler</ulink> (minus libraries). Absolutely
723 required for building GHC.</para>
728 <term><literal>glafp-utils</literal></term>
729 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
731 <para>Utility programs, some of which are used by the
732 build/installation system. Required for pretty much
738 <term><literal>green-card</literal></term>
739 <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
742 url="http://www.haskell.org/greencard/">Green Card</ulink>
743 system for generating Haskell foreign function
749 <term><literal>haggis</literal></term>
750 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
753 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
754 Haskell GUI framework.</para>
759 <term><literal>haddock</literal></term>
760 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
763 url="http://www.haskell.org/haddock/">Haddock</ulink>
764 documentation tool.</para>
769 <term><literal>happy</literal></term>
770 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
773 url="http://www.haskell.org/happy/">Happy</ulink> Parser
779 <term><literal>hdirect</literal></term>
780 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
783 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
784 Haskell interoperability tool.</para>
789 <term><literal>hood</literal></term>
790 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
792 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
793 Object Observation Debugger</ulink>.</para>
798 <term><literal>hslibs</literal></term>
799 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
801 <para>Supplemental libraries for GHC
802 (<emphasis>required</emphasis> for building GHC).</para>
807 <term><literal>libraries</literal></term>
808 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
810 <para>Hierarchical Haskell library suite
811 (<emphasis>required</emphasis> for building GHC).</para>
816 <term><literal>mhms</literal></term>
817 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
819 <para>The Modular Haskell Metric System.</para>
824 <term><literal>nofib</literal></term>
825 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
827 <para>The NoFib suite: A collection of Haskell programs used
828 primarily for benchmarking.</para>
833 <term><literal>testsuite</literal></term>
834 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
836 <para>A testing framework, including GHC's regression test
842 <para>So, to build GHC you need at least the
843 <literal>ghc</literal>, <literal>libraries</literal> and
844 <literal>hslibs</literal> projects (a GHC source distribution will
845 already include the bits you need).</para>
848 <sect1 id="sec-build-checks">
849 <title>Things to check before you start</title>
851 <para>Here's a list of things to check before you get
857 <indexterm><primary>Disk space needed</primary></indexterm>
858 <para>Disk space needed: from about 100Mb for a basic GHC
859 build, up to probably 500Mb for a GHC build with everything
860 included (libraries built several different ways,
865 <para>Use an appropriate machine / operating system. <xref
866 linkend="sec-port-info"> lists the supported platforms; if
867 yours isn't amongst these then you can try porting GHC (see
868 <xref linkend="sec-porting-ghc">).</para>
872 <para>Be sure that the “pre-supposed” utilities are
873 installed. <Xref LinkEnd="sec-pre-supposed">
878 <para>If you have any problem when building or installing the
879 Glasgow tools, please check the “known pitfalls” (<Xref
880 LinkEnd="sec-build-pitfalls">). Also check the FAQ for the
881 version you're building, which is part of the User's Guide and
882 available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
885 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
887 <para>If you feel there is still some shortcoming in our
888 procedure or instructions, please report it.</para>
890 <para>For GHC, please see the <ulink
891 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
892 section of the GHC Users' Guide</ulink>, to maximise the
893 usefulness of your report.</para>
895 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
896 <para>If in doubt, please send a message to
897 <email>glasgow-haskell-bugs@haskell.org</email>.
898 <indexterm><primary>bugs</primary><secondary>mailing
899 list</secondary></indexterm></para>
904 <sect1 id="sec-port-info">
905 <title>What machines the Glasgow tools run on</title>
907 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
908 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
909 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
911 <para>The main question is whether or not the Haskell compiler
912 (GHC) runs on your platform.</para>
914 <para>A “platform” is a
915 architecture/manufacturer/operating-system combination, such as
916 <literal>sparc-sun-solaris2</literal>. Other common ones are
917 <literal>alpha-dec-osf2</literal>,
918 <literal>hppa1.1-hp-hpux9</literal>,
919 <literal>i386-unknown-linux</literal>,
920 <literal>i386-unknown-solaris2</literal>,
921 <literal>i386-unknown-freebsd</literal>,
922 <literal>i386-unknown-cygwin32</literal>,
923 <literal>m68k-sun-sunos4</literal>,
924 <literal>mips-sgi-irix5</literal>,
925 <literal>sparc-sun-sunos4</literal>,
926 <literal>sparc-sun-solaris2</literal>,
927 <literal>powerpc-ibm-aix</literal>.</para>
929 <para>Some libraries may only work on a limited number of
930 platforms; for example, a sockets library is of no use unless the
931 operating system supports the underlying BSDisms.</para>
934 <title>What platforms the Haskell compiler (GHC) runs on</title>
936 <indexterm><primary>fully-supported platforms</primary></indexterm>
937 <indexterm><primary>native-code generator</primary></indexterm>
938 <indexterm><primary>registerised ports</primary></indexterm>
939 <indexterm><primary>unregisterised ports</primary></indexterm>
941 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
942 native-code generator; (b) next best is a
943 “registerised” port; (c) the bare minimum is an
944 “unregisterised” port.
945 (“Unregisterised” is so terrible that we won't say
946 more about it).</para>
948 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
949 FreeBSD and Linux, so those are the best supported platforms,
950 unsurprisingly.</para>
952 <para>Here's everything that's known about GHC ports. We
953 identify platforms by their “canonical”
954 CPU/Manufacturer/OS triple.</para>
958 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
959 <indexterm><primary>alpha-dec-osf</primary></indexterm>
960 <indexterm><primary>alpha-dec-linux</primary></indexterm>
961 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
962 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
963 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
966 <para>The OSF port is currently working (as of GHC version
967 5.02.1) and well supported. The native code generator is
968 currently non-working. Other operating systems will
969 require some minor porting.</para>
974 <term>sparc-sun-sunos4</term>
975 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
977 <para>Probably works with minor tweaks, hasn't been tested
983 <term>sparc-sun-solaris2</term>
984 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
986 <para>Fully supported (at least for Solaris 2.7),
987 including native-code generator.</para>
992 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
993 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
995 <para>A registerised port is available for version 4.08,
996 but GHC hasn't been built on that platform since (as far
997 as we know). No native-code generator.</para>
1002 <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
1003 <indexterm><primary>i386-*-linux</primary></indexterm>
1005 <para>GHC works registerised and has a native code
1006 generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
1007 or later. NOTE about <literal>glibc</literal> versions:
1008 GHC binaries built on a system running <literal>glibc
1009 2.0</literal> won't work on a system running
1010 <literal>glibc 2.1</literal>, and vice versa. In general,
1011 don't expect compatibility between
1012 <literal>glibc</literal> versions, even if the shared
1013 library version hasn't changed.</para>
1018 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
1020 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1022 <para>GHC works registerised. Pre-built packages are
1023 available in the native package format, so if you just
1024 need binaries you're better off just installing the
1025 package (it might even be on your installation
1031 <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
1032 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1034 <para>Supported, with native code generator. Packages are
1035 available through the ports system in the native package
1041 <term>i386-unknown-netbsd (PCs running NetBSD and
1043 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1045 <para>Will require some minor porting effort, but should
1046 work registerised.</para>
1051 <term>i386-unknown-mingw32 (PCs running Windows)</term>
1052 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1054 <para>Fully supported under Win9x, WinNT, Win2k, and
1055 WinXP. Includes a native code generator. Building from
1056 source requires a recent <ulink
1057 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1058 to be installed.</para>
1063 <term>ia64-unknown-linux</term>
1064 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1066 <para>GHC currently works unregisterised. A registerised
1067 port is in progress.</para>
1072 <term>mips-sgi-irix5</term>
1073 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1075 <para>Port has worked in the past, but hasn't been tested
1076 for some time (and will certainly have rotted in various
1077 ways). As usual, we don't have access to machines and
1078 there hasn't been an overwhelming demand for this port,
1079 but feel free to get in touch.</para>
1084 <term>powerpc-ibm-aix</term>
1085 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1087 <para>Port currently doesn't work, needs some minimal
1088 porting effort. As usual, we don't have access to
1089 machines and there hasn't been an overwhelming demand for
1090 this port, but feel free to get in touch.</para>
1095 <term>powerpc-apple-darwin</term>
1096 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1098 <para>Supported registerised. No native code
1104 <term>powerpc-apple-linux</term>
1105 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1107 <para>Not supported (yet).</para>
1112 <para>Various other systems have had GHC ported to them in the
1113 distant past, including various Motorola 68k boxes. The 68k
1114 support still remains, but porting to one of these systems will
1115 certainly be a non-trivial task.</para>
1119 <title>What machines the other tools run on</title>
1121 <para>Unless you hear otherwise, the other tools work if GHC
1127 <sect1 id="sec-pre-supposed">
1128 <title>Installing pre-supposed utilities</title>
1130 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1131 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1133 <para>Here are the gory details about some utility programs you
1134 may need; <command>perl</command>, <command>gcc</command> and
1135 <command>happy</command> are the only important
1136 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1137 important if you're going for Parallel Haskell.) The
1138 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1139 script will tell you if you are missing something.</para>
1145 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1146 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1148 <para><emphasis>You have to have Perl to proceed!</emphasis>
1149 Perl version 5 at least is required. GHC has been known to
1150 tickle bugs in Perl, so if you find that Perl crashes when
1151 running GHC try updating (or downgrading) your Perl
1152 installation. Versions of Perl that we use and are known to
1153 be fairly stable are 5.005 and 5.6.1.</para>
1155 <para>For Win32 platforms, you should use the binary
1156 supplied in the InstallShield (copy it to
1157 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1160 <para>Perl should be put somewhere so that it can be invoked
1161 by the <literal>#!</literal> script-invoking
1162 mechanism. The full pathname may need to be less than 32
1163 characters long on some systems.</para>
1168 <term>GNU C (<command>gcc</command>)</term>
1169 <indexterm><primary>pre-supposed: GCC (GNU C
1170 compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
1171 compiler), pre-supposed</primary></indexterm>
1173 <para>We recommend using GCC version 2.95.2 on all
1174 platforms. Failing that, version 2.7.2 is stable on most
1175 platforms. Earlier versions of GCC can be assumed not to
1176 work, and versions in between 2.7.2 and 2.95.2 (including
1177 <command>egcs</command>) have varying degrees of stability
1178 depending on the platform.</para>
1180 <para>If your GCC dies with “internal error” on
1181 some GHC source file, please let us know, so we can report
1182 it and get things improved. (Exception: on iX86
1183 boxes—you may need to fiddle with GHC's
1184 <option>-monly-N-regs</option> option; see the User's
1190 <term>GNU Make</term>
1191 <indexterm><primary>make</primary><secondary>GNU</secondary>
1194 <para>The fptools build system makes heavy use of features
1195 specific to GNU <command>make</command>, so you must have
1196 this installed in order to build any of the fptools
1203 <indexterm><primary>Happy</primary></indexterm>
1205 <para>Happy is a parser generator tool for Haskell, and is
1206 used to generate GHC's parsers. Happy is written in
1207 Haskell, and is a project in the CVS repository
1208 (<literal>fptools/happy</literal>). It can be built from
1209 source, but bear in mind that you'll need GHC installed in
1210 order to build it. To avoid the chicken/egg problem,
1211 install a binary distribtion of either Happy or GHC to get
1212 started. Happy distributions are available from <ulink
1213 url="http://www.haskell.org/happy/">Happy's Web
1214 Page</ulink>.</para>
1219 <term>Autoconf</term>
1220 <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
1221 <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
1223 <para>GNU Autoconf is needed if you intend to build from the
1224 CVS sources, it is <emphasis>not</emphasis> needed if you
1225 just intend to build a standard source distribution.</para>
1227 <para>Autoconf builds the <command>configure</command>
1228 script from <filename>configure.in</filename> and
1229 <filename>aclocal.m4</filename>. If you modify either of
1230 these files, you'll need <command>autoconf</command> to
1231 rebuild <filename>configure</filename>.</para>
1236 <term><command>sed</command></term>
1237 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1238 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1240 <para>You need a working <command>sed</command> if you are
1241 going to build from sources. The build-configuration stuff
1242 needs it. GNU sed version 2.0.4 is no good! It has a bug
1243 in it that is tickled by the build-configuration. 2.0.5 is
1244 OK. Others are probably OK too (assuming we don't create too
1245 elaborate configure scripts.)</para>
1250 <para>One <literal>fptools</literal> project is worth a quick note
1251 at this point, because it is useful for all the others:
1252 <literal>glafp-utils</literal> contains several utilities which
1253 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1254 Like <command>lndir</command> for creating symbolic link
1257 <sect2 id="pre-supposed-gph-tools">
1258 <title>Tools for building parallel GHC (GPH)</title>
1262 <term>PVM version 3:</term>
1263 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1264 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1266 <para>PVM is the Parallel Virtual Machine on which
1267 Parallel Haskell programs run. (You only need this if you
1268 plan to run Parallel Haskell. Concurent Haskell, which
1269 runs concurrent threads on a uniprocessor doesn't need
1270 it.) Underneath PVM, you can have (for example) a network
1271 of workstations (slow) or a multiprocessor box
1274 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1275 It is readily available on the net; I think I got it from
1276 <literal>research.att.com</literal>, in
1277 <filename>netlib</filename>.</para>
1279 <para>A PVM installation is slightly quirky, but easy to
1280 do. Just follow the <filename>Readme</filename>
1281 instructions.</para>
1286 <term><command>bash</command>:</term>
1287 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1289 <para>Sadly, the <command>gr2ps</command> script, used to
1290 convert “parallelism profiles” to PostScript,
1291 is written in Bash (GNU's Bourne Again shell). This bug
1292 will be fixed (someday).</para>
1298 <sect2 id="pre-supposed-doc-tools">
1299 <title>Tools for building the Documentation</title>
1301 <para>The following additional tools are required if you want to
1302 format the documentation that comes with the
1303 <literal>fptools</literal> projects:</para>
1307 <term>DocBook</term>
1308 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
1309 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
1311 <para>All our documentation is written in SGML, using the
1312 DocBook DTD. Instructions on installing and configuring
1313 the DocBook tools are in the installation guide (in the
1314 GHC user guide).</para>
1320 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
1321 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
1323 <para>A decent TeX distribution is required if you want to
1324 produce printable documentation. We recomment teTeX,
1325 which includes just about everything you need.</para>
1330 <para> In order to actually build any documentation, you need to
1331 set <constant>SGMLDocWays</constant> in your
1332 <filename>build.mk</filename>. Valid values to add to this list
1333 are: <literal>dvi</literal>, <literal>ps</literal>,
1334 <literal>pdf</literal>, <literal>html</literal>, and
1335 <literal>rtf</literal>.</para>
1338 <sect2 id="pre-supposed-other-tools">
1339 <title>Other useful tools</title>
1344 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1345 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1347 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1348 to build a couple of utilities in
1349 <literal>glafp-utils</literal>. Depending on your
1350 operating system, the supplied <command>lex</command> may
1351 or may not work; you should get the GNU version.</para>
1358 <sect1 id="sec-building-from-source">
1359 <title>Building from source</title>
1361 <indexterm><primary>Building from source</primary></indexterm>
1362 <indexterm><primary>Source, building from</primary></indexterm>
1364 <para>You've been rash enough to want to build some of the Glasgow
1365 Functional Programming tools (GHC, Happy, nofib, etc.) from
1366 source. You've slurped the source, from the CVS repository or
1367 from a source distribution, and now you're sitting looking at a
1368 huge mound of bits, wondering what to do next.</para>
1370 <para>Gingerly, you type <command>make</command>. Wrong
1373 <para>This rest of this guide is intended for duffers like me, who
1374 aren't really interested in Makefiles and systems configurations,
1375 but who need a mental model of the interlocking pieces so that
1376 they can make them work, extend them consistently when adding new
1377 software, and lay hands on them gently when they don't
1380 <sect2 id="sec-source-tree">
1381 <title>Your source tree</title>
1383 <para>The source code is held in your <emphasis>source
1384 tree</emphasis>. The root directory of your source tree
1385 <emphasis>must</emphasis> contain the following directories and
1390 <para><filename>Makefile</filename>: the root
1395 <para><filename>mk/</filename>: the directory that contains
1396 the main Makefile code, shared by all the
1397 <literal>fptools</literal> software.</para>
1401 <para><filename>configure.in</filename>,
1402 <filename>config.sub</filename>,
1403 <filename>config.guess</filename>: these files support the
1404 configuration process.</para>
1408 <para><filename>install-sh</filename>.</para>
1412 <para>All the other directories are individual
1413 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1414 system—for example, the Glasgow Haskell Compiler
1415 (<literal>ghc</literal>), the Happy parser generator
1416 (<literal>happy</literal>), the <literal>nofib</literal>
1417 benchmark suite, and so on. You can have zero or more of these.
1418 Needless to say, some of them are needed to build others.</para>
1420 <para>The important thing to remember is that even if you want
1421 only one project (<literal>happy</literal>, say), you must have
1422 a source tree whose root directory contains
1423 <filename>Makefile</filename>, <filename>mk/</filename>,
1424 <filename>configure.in</filename>, and the project(s) you want
1425 (<filename>happy/</filename> in this case). You cannot get by
1426 with just the <filename>happy/</filename> directory.</para>
1430 <title>Build trees</title>
1431 <indexterm><primary>build trees</primary></indexterm>
1432 <indexterm><primary>link trees, for building</primary></indexterm>
1434 <para>If you just want to build the software once on a single
1435 platform, then your source tree can also be your build tree, and
1436 you can skip the rest of this section.</para>
1438 <para>We often want to build multiple versions of our software
1439 for different architectures, or with different options
1440 (e.g. profiling). It's very desirable to share a single copy of
1441 the source code among all these builds.</para>
1443 <para>So for every source tree we have zero or more
1444 <emphasis>build trees</emphasis>. Each build tree is initially
1445 an exact copy of the source tree, except that each file is a
1446 symbolic link to the source file, rather than being a copy of
1447 the source file. There are “standard” Unix
1448 utilities that make such copies, so standard that they go by
1450 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1451 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1452 are two (If you don't have either, the source distribution
1453 includes sources for the X11
1454 <command>lndir</command>—check out
1455 <filename>fptools/glafp-utils/lndir</filename>). See <Xref
1456 LinkEnd="sec-storysofar"> for a typical invocation.</para>
1458 <para>The build tree does not need to be anywhere near the
1459 source tree in the file system. Indeed, one advantage of
1460 separating the build tree from the source is that the build tree
1461 can be placed in a non-backed-up partition, saving your systems
1462 support people from backing up untold megabytes of
1463 easily-regenerated, and rapidly-changing, gubbins. The golden
1464 rule is that (with a single exception—<XRef
1465 LinkEnd="sec-build-config">) <emphasis>absolutely everything in
1466 the build tree is either a symbolic link to the source tree, or
1467 else is mechanically generated</emphasis>. It should be
1468 perfectly OK for your build tree to vanish overnight; an hour or
1469 two compiling and you're on the road again.</para>
1471 <para>You need to be a bit careful, though, that any new files
1472 you create (if you do any development work) are in the source
1473 tree, not a build tree!</para>
1475 <para>Remember, that the source files in the build tree are
1476 <emphasis>symbolic links</emphasis> to the files in the source
1477 tree. (The build tree soon accumulates lots of built files like
1478 <filename>Foo.o</filename>, as well.) You can
1479 <emphasis>delete</emphasis> a source file from the build tree
1480 without affecting the source tree (though it's an odd thing to
1481 do). On the other hand, if you <emphasis>edit</emphasis> a
1482 source file from the build tree, you'll edit the source-tree
1483 file directly. (You can set up Emacs so that if you edit a
1484 source file from the build tree, Emacs will silently create an
1485 edited copy of the source file in the build tree, leaving the
1486 source file unchanged; but the danger is that you think you've
1487 edited the source file whereas actually all you've done is edit
1488 the build-tree copy. More commonly you do want to edit the
1489 source file.)</para>
1491 <para>Like the source tree, the top level of your build tree
1492 must be (a linked copy of) the root directory of the
1493 <literal>fptools</literal> suite. Inside Makefiles, the root of
1494 your build tree is called
1495 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1496 In the rest of this document path names are relative to
1497 <constant>$(FPTOOLS_TOP)</constant> unless
1498 otherwise stated. For example, the file
1499 <filename>ghc/mk/target.mk</filename> is actually
1500 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
1503 <sect2 id="sec-build-config">
1504 <title>Getting the build you want</title>
1506 <para>When you build <literal>fptools</literal> you will be
1507 compiling code on a particular <emphasis>host
1508 platform</emphasis>, to run on a particular <emphasis>target
1509 platform</emphasis> (usually the same as the host
1510 platform)<indexterm><primary>platform</primary></indexterm>.
1511 The difficulty is that there are minor differences between
1512 different platforms; minor, but enough that the code needs to be
1513 a bit different for each. There are some big differences too:
1514 for a different architecture we need to build GHC with a
1515 different native-code generator.</para>
1517 <para>There are also knobs you can turn to control how the
1518 <literal>fptools</literal> software is built. For example, you
1519 might want to build GHC optimised (so that it runs fast) or
1520 unoptimised (so that you can compile it fast after you've
1521 modified it. Or, you might want to compile it with debugging on
1522 (so that extra consistency-checking code gets included) or off.
1525 <para>All of this stuff is called the
1526 <emphasis>configuration</emphasis> of your build. You set the
1527 configuration using a three-step process.</para>
1531 <term>Step 1: get ready for configuration.</term>
1533 <para>Change directory to
1534 <constant>$(FPTOOLS_TOP)</constant> and
1536 <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
1537 (with no arguments). This GNU program converts
1538 <filename><constant>$(FPTOOLS_TOP)</constant>/configure.in</filename>
1539 to a shell script called
1540 <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
1543 <para>Some projects, including GHC, have their own
1544 configure script. If there's an
1545 <constant>$(FPTOOLS_TOP)/<project>/configure.in</constant>,
1546 then you need to run <command>autoconf</command> in that
1547 directory too.</para>
1549 <para>Both these steps are completely
1550 platform-independent; they just mean that the
1551 human-written file (<filename>configure.in</filename>) can
1552 be short, although the resulting shell script,
1553 <command>configure</command>, and
1554 <filename>mk/config.h.in</filename>, are long.</para>
1556 <para>In case you don't have <command>autoconf</command>
1557 we distribute the results, <command>configure</command>,
1558 and <filename>mk/config.h.in</filename>, with the source
1559 distribution. They aren't kept in the repository,
1565 <term>Step 2: system configuration.</term>
1567 <para>Runs the newly-created <command>configure</command>
1568 script, thus:</para>
1571 ./configure <optional><parameter>args</parameter></optional>
1574 <para><command>configure</command>'s mission is to scurry
1575 round your computer working out what architecture it has,
1576 what operating system, whether it has the
1577 <Function>vfork</Function> system call, where
1578 <command>yacc</command> is kept, whether
1579 <command>gcc</command> is available, where various obscure
1580 <literal>#include</literal> files are, whether it's a
1581 leap year, and what the systems manager had for lunch. It
1582 communicates these snippets of information in two
1589 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1591 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1592 substituting for things between
1593 “<literal>@</literal>” brackets. So,
1594 “<literal>@HaveGcc@</literal>” will be
1595 replaced by “<literal>YES</literal>” or
1596 “<literal>NO</literal>” depending on what
1597 <command>configure</command> finds.
1598 <filename>mk/config.mk</filename> is included by every
1599 Makefile (directly or indirectly), so the
1600 configuration information is thereby communicated to
1601 all Makefiles.</para>
1605 <para> It translates
1606 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1608 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1609 The latter is <literal>#include</literal>d by
1610 various C programs, which can thereby make use of
1611 configuration information.</para>
1615 <para><command>configure</command> takes some optional
1616 arguments. Use <literal>./configure --help</literal> to
1617 get a list of the available arguments. Here are some of
1618 the ones you might need:</para>
1622 <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
1623 <indexterm><primary><literal>--with-ghc</literal></primary>
1626 <para>Specifies the path to an installed GHC which
1627 you would like to use. This compiler will be used
1628 for compiling GHC-specific code (eg. GHC itself).
1629 This option <emphasis>cannot</emphasis> be specified
1630 using <filename>build.mk</filename> (see later),
1631 because <command>configure</command> needs to
1632 auto-detect the version of GHC you're using. The
1633 default is to look for a compiler named
1634 <literal>ghc</literal> in your path.</para>
1639 <term><literal>--with-hc=<parameter>path</parameter></literal></term>
1640 <indexterm><primary><literal>--with-hc</literal></primary>
1643 <para>Specifies the path to any installed Haskell
1644 compiler. This compiler will be used for compiling
1645 generic Haskell code. The default is to use
1646 <literal>ghc</literal>.</para>
1651 <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
1652 <indexterm><primary><literal>--with-gcc</literal></primary>
1655 <para>Specifies the path to the installed GCC. This
1656 compiler will be used to compile all C files,
1657 <emphasis>except</emphasis> any generated by the
1658 installed Haskell compiler, which will have its own
1659 idea of which C compiler (if any) to use. The
1660 default is to use <literal>gcc</literal>.</para>
1665 <para><command>configure</command> caches the results of
1666 its run in <filename>config.cache</filename>. Quite often
1667 you don't want that; you're running
1668 <command>configure</command> a second time because
1669 something has changed. In that case, simply delete
1670 <filename>config.cache</filename>.</para>
1675 <term>Step 3: build configuration.</term>
1677 <para>Next, you say how this build of
1678 <literal>fptools</literal> is to differ from the standard
1679 defaults by creating a new file
1680 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1681 <emphasis>in the build tree</emphasis>. This file is the
1682 one and only file you edit in the build tree, precisely
1683 because it says how this build differs from the source.
1684 (Just in case your build tree does die, you might want to
1685 keep a private directory of <filename>build.mk</filename>
1686 files, and use a symbolic link in each build tree to point
1687 to the appropriate one.) So
1688 <filename>mk/build.mk</filename> never exists in the
1689 source tree—you create one in each build tree from
1690 the template. We'll discuss what to put in it
1696 <para>And that's it for configuration. Simple, eh?</para>
1698 <para>What do you put in your build-specific configuration file
1699 <filename>mk/build.mk</filename>? <emphasis>For almost all
1700 purposes all you will do is put make variable definitions that
1701 override those in</emphasis>
1702 <filename>mk/config.mk.in</filename>. The whole point of
1703 <filename>mk/config.mk.in</filename>—and its derived
1704 counterpart <filename>mk/config.mk</filename>—is to define
1705 the build configuration. It is heavily commented, as you will
1706 see if you look at it. So generally, what you do is look at
1707 <filename>mk/config.mk.in</filename>, and add definitions in
1708 <filename>mk/build.mk</filename> that override any of the
1709 <filename>config.mk</filename> definitions that you want to
1710 change. (The override occurs because the main boilerplate file,
1711 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1712 includes <filename>build.mk</filename> after
1713 <filename>config.mk</filename>.)</para>
1715 <para>For example, <filename>config.mk.in</filename> contains
1716 the definition:</para>
1719 GhcHcOpts=-O -Rghc-timing
1722 <para>The accompanying comment explains that this is the list of
1723 flags passed to GHC when building GHC itself. For doing
1724 development, it is wise to add <literal>-DDEBUG</literal>, to
1725 enable debugging code. So you would add the following to
1726 <filename>build.mk</filename>:</para>
1728 <para>or, if you prefer,</para>
1731 GhcHcOpts += -DDEBUG
1734 <para>GNU <command>make</command> allows existing definitions to
1735 have new text appended using the “<literal>+=</literal>”
1736 operator, which is quite a convenient feature.)</para>
1738 <para>If you want to remove the <literal>-O</literal> as well (a
1739 good idea when developing, because the turn-around cycle gets a
1740 lot quicker), you can just override
1741 <literal>GhcLibHcOpts</literal> altogether:</para>
1744 GhcHcOpts=-DDEBUG -Rghc-timing
1747 <para>When reading <filename>config.mk.in</filename>, remember
1748 that anything between “@...@” signs is going to be substituted
1749 by <command>configure</command> later. You
1750 <emphasis>can</emphasis> override the resulting definition if
1751 you want, but you need to be a bit surer what you are doing.
1752 For example, there's a line that says:</para>
1758 <para>This defines the Make variables <constant>YACC</constant>
1759 to the pathname for a <command>yacc</command> that
1760 <command>configure</command> finds somewhere. If you have your
1761 own pet <command>yacc</command> you want to use instead, that's
1762 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1768 <para>You do not <emphasis>have</emphasis> to have a
1769 <filename>mk/build.mk</filename> file at all; if you don't,
1770 you'll get all the default settings from
1771 <filename>mk/config.mk.in</filename>.</para>
1773 <para>You can also use <filename>build.mk</filename> to override
1774 anything that <command>configure</command> got wrong. One place
1775 where this happens often is with the definition of
1776 <constant>FPTOOLS_TOP_ABS</constant>: this
1777 variable is supposed to be the canonical path to the top of your
1778 source tree, but if your system uses an automounter then the
1779 correct directory is hard to find automatically. If you find
1780 that <command>configure</command> has got it wrong, just put the
1781 correct definition in <filename>build.mk</filename>.</para>
1785 <sect2 id="sec-storysofar">
1786 <title>The story so far</title>
1788 <para>Let's summarise the steps you need to carry to get
1789 yourself a fully-configured build tree from scratch.</para>
1793 <para> Get your source tree from somewhere (CVS repository
1794 or source distribution). Say you call the root directory
1795 <filename>myfptools</filename> (it does not have to be
1796 called <filename>fptools</filename>). Make sure that you
1797 have the essential files (see <XRef
1798 LinkEnd="sec-source-tree">).</para>
1803 <para>(Optional) Use <command>lndir</command> or
1804 <command>mkshadowdir</command> to create a build tree.</para>
1808 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1811 <para>(N.B. <command>mkshadowdir</command>'s first argument
1812 is taken relative to its second.) You probably want to give
1813 the build tree a name that suggests its main defining
1814 characteristic (in your mind at least), in case you later
1819 <para>Change directory to the build tree. Everything is
1820 going to happen there now.</para>
1823 $ cd /scratch/joe-bloggs/myfptools-sun4
1829 <para>Prepare for system configuration:</para>
1835 <para>(You can skip this step if you are starting from a
1836 source distribution, and you already have
1837 <filename>configure</filename> and
1838 <filename>mk/config.h.in</filename>.)</para>
1840 <para>Some projects, including GHC itself, have their own
1841 configure scripts, so it is necessary to run autoconf again
1842 in the appropriate subdirectories. eg:</para>
1845 $ (cd ghc; autoconf)
1850 <para>Do system configuration:</para>
1856 <para>Don't forget to check whether you need to add any
1857 arguments to <literal>configure</literal>; for example, a
1858 common requirement is to specify which GHC to use with
1859 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1863 <para>Create the file <filename>mk/build.mk</filename>,
1864 adding definitions for your desired configuration
1873 <para>You can make subsequent changes to
1874 <filename>mk/build.mk</filename> as often as you like. You do
1875 not have to run any further configuration programs to make these
1876 changes take effect. In theory you should, however, say
1877 <command>gmake clean</command>, <command>gmake all</command>,
1878 because configuration option changes could affect
1879 anything—but in practice you are likely to know what's
1884 <title>Making things</title>
1886 <para>At this point you have made yourself a fully-configured
1887 build tree, so you are ready to start building real
1890 <para>The first thing you need to know is that <emphasis>you
1891 must use GNU <command>make</command>, usually called
1892 <command>gmake</command>, not standard Unix
1893 <command>make</command></emphasis>. If you use standard Unix
1894 <command>make</command> you will get all sorts of error messages
1895 (but no damage) because the <literal>fptools</literal>
1896 <command>Makefiles</command> use GNU <command>make</command>'s
1897 facilities extensively.</para>
1899 <para>To just build the whole thing, <command>cd</command> to
1900 the top of your <literal>fptools</literal> tree and type
1901 <command>gmake</command>. This will prepare the tree and build
1902 the various projects in the correct order.</para>
1906 <sect2 id="sec-standard-targets">
1907 <title>Standard Targets</title>
1908 <indexterm><primary>targets, standard makefile</primary></indexterm>
1909 <indexterm><primary>makefile targets</primary></indexterm>
1911 <para>In any directory you should be able to make the following:</para>
1915 <term><literal>boot</literal></term>
1917 <para>does the one-off preparation required to get ready
1918 for the real work. Notably, it does <command>gmake
1919 depend</command> in all directories that contain programs.
1920 It also builds the necessary tools for compilation to
1923 <para>Invoking the <literal>boot</literal> target
1924 explicitly is not normally necessary. From the top-level
1925 <literal>fptools</literal> directory, invoking
1926 <literal>gmake</literal> causes <literal>gmake boot
1927 all</literal> to be invoked in each of the project
1928 subdirectories, in the order specified by
1929 <literal>$(AllTargets)</literal> in
1930 <literal>config.mk</literal>.</para>
1932 <para>If you're working in a subdirectory somewhere and
1933 need to update the dependencies, <literal>gmake
1934 boot</literal> is a good way to do it.</para>
1939 <term><literal>all</literal></term>
1941 <para>makes all the final target(s) for this Makefile.
1942 Depending on which directory you are in a “final
1943 target” may be an executable program, a library
1944 archive, a shell script, or a Postscript file. Typing
1945 <command>gmake</command> alone is generally the same as
1946 typing <command>gmake all</command>.</para>
1951 <term><literal>install</literal></term>
1953 <para>installs the things built by <literal>all</literal>
1954 (except for the documentation). Where does it install
1955 them? That is specified by
1956 <filename>mk/config.mk.in</filename>; you can override it
1957 in <filename>mk/build.mk</filename>, or by running
1958 <command>configure</command> with command-line arguments
1959 like <literal>--bindir=/home/simonpj/bin</literal>; see
1960 <literal>./configure --help</literal> for the full
1966 <term><literal>install-docs</literal></term>
1968 <para>installs the documentation. Otherwise behaves just
1969 like <literal>install</literal>.</para>
1974 <term><literal>uninstall</literal></term>
1976 <para>reverses the effect of
1977 <literal>install</literal>.</para>
1982 <term><literal>clean</literal></term>
1984 <para>Delete all files from the current directory that are
1985 normally created by building the program. Don't delete
1986 the files that record the configuration, or files
1987 generated by <command>gmake boot</command>. Also preserve
1988 files that could be made by building, but normally aren't
1989 because the distribution comes with them.</para>
1994 <term><literal>distclean</literal></term>
1996 <para>Delete all files from the current directory that are
1997 created by configuring or building the program. If you
1998 have unpacked the source and built the program without
1999 creating any other files, <literal>make
2000 distclean</literal> should leave only the files that were
2001 in the distribution.</para>
2006 <term><literal>mostlyclean</literal></term>
2008 <para>Like <literal>clean</literal>, but may refrain from
2009 deleting a few files that people normally don't want to
2015 <term><literal>maintainer-clean</literal></term>
2017 <para>Delete everything from the current directory that
2018 can be reconstructed with this Makefile. This typically
2019 includes everything deleted by
2020 <literal>distclean</literal>, plus more: C source files
2021 produced by Bison, tags tables, Info files, and so
2024 <para>One exception, however: <literal>make
2025 maintainer-clean</literal> should not delete
2026 <filename>configure</filename> even if
2027 <filename>configure</filename> can be remade using a rule
2028 in the <filename>Makefile</filename>. More generally,
2029 <literal>make maintainer-clean</literal> should not delete
2030 anything that needs to exist in order to run
2031 <filename>configure</filename> and then begin to build the
2037 <term><literal>check</literal></term>
2039 <para>run the test suite.</para>
2044 <para>All of these standard targets automatically recurse into
2045 sub-directories. Certain other standard targets do not:</para>
2049 <term><literal>configure</literal></term>
2051 <para>is only available in the root directory
2052 <constant>$(FPTOOLS_TOP)</constant>; it has
2053 been discussed in <XRef
2054 LinkEnd="sec-build-config">.</para>
2059 <term><literal>depend</literal></term>
2061 <para>make a <filename>.depend</filename> file in each
2062 directory that needs it. This <filename>.depend</filename>
2063 file contains mechanically-generated dependency
2064 information; for example, suppose a directory contains a
2065 Haskell source module <filename>Foo.lhs</filename> which
2066 imports another module <literal>Baz</literal>. Then the
2067 generated <filename>.depend</filename> file will contain
2068 the dependency:</para>
2074 <para>which says that the object file
2075 <filename>Foo.o</filename> depends on the interface file
2076 <filename>Baz.hi</filename> generated by compiling module
2077 <literal>Baz</literal>. The <filename>.depend</filename>
2078 file is automatically included by every Makefile.</para>
2083 <term><literal>binary-dist</literal></term>
2085 <para>make a binary distribution. This is the target we
2086 use to build the binary distributions of GHC and
2092 <term><literal>dist</literal></term>
2094 <para>make a source distribution. Note that this target
2095 does “make distclean” as part of its work;
2096 don't use it if you want to keep what you've built.</para>
2101 <para>Most <filename>Makefile</filename>s have targets other
2102 than these. You can discover them by looking in the
2103 <filename>Makefile</filename> itself.</para>
2107 <title>Using a project from the build tree</title>
2109 <para>If you want to build GHC (say) and just use it direct from
2110 the build tree without doing <literal>make install</literal>
2111 first, you can run the in-place driver script:
2112 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2114 <para> Do <emphasis>NOT</emphasis> use
2115 <filename>ghc/compiler/ghc</filename>, or
2116 <filename>ghc/compiler/ghc-5.xx</filename>, as these are the
2117 scripts intended for installation, and contain hard-wired paths
2118 to the installed libraries, rather than the libraries in the
2121 <para>Happy can similarly be run from the build tree, using
2122 <filename>happy/src/happy-inplace</filename>.</para>
2126 <title>Fast Making</title>
2128 <indexterm><primary>fastmake</primary></indexterm>
2129 <indexterm><primary>dependencies, omitting</primary></indexterm>
2130 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2132 <para>Sometimes the dependencies get in the way: if you've made
2133 a small change to one file, and you're absolutely sure that it
2134 won't affect anything else, but you know that
2135 <command>make</command> is going to rebuild everything anyway,
2136 the following hack may be useful:</para>
2142 <para>This tells the make system to ignore dependencies and just
2143 build what you tell it to. In other words, it's equivalent to
2144 temporarily removing the <filename>.depend</filename> file in
2145 the current directory (where <command>mkdependHS</command> and
2146 friends store their dependency information).</para>
2148 <para>A bit of history: GHC used to come with a
2149 <command>fastmake</command> script that did the above job, but
2150 GNU make provides the features we need to do it without
2151 resorting to a script. Also, we've found that fastmaking is
2152 less useful since the advent of GHC's recompilation checker (see
2153 the User's Guide section on "Separate Compilation").</para>
2157 <sect1 id="sec-makefile-arch">
2158 <title>The <filename>Makefile</filename> architecture</title>
2159 <indexterm><primary>makefile architecture</primary></indexterm>
2161 <para><command>make</command> is great if everything
2162 works—you type <command>gmake install</command> and lo! the
2163 right things get compiled and installed in the right places. Our
2164 goal is to make this happen often, but somehow it often doesn't;
2165 instead some weird error message eventually emerges from the
2166 bowels of a directory you didn't know existed.</para>
2168 <para>The purpose of this section is to give you a road-map to
2169 help you figure out what is going right and what is going
2173 <title>Debugging</title>
2175 <para>Debugging <filename>Makefile</filename>s is something of a
2176 black art, but here's a couple of tricks that we find
2177 particularly useful. The following command allows you to see
2178 the contents of any make variable in the context of the current
2179 <filename>Makefile</filename>:</para>
2181 <screen>$ make show VALUE=HS_SRCS</screen>
2183 <para>where you can replace <literal>HS_SRCS</literal> with the
2184 name of any variable you wish to see the value of.</para>
2186 <para>GNU make has a <option>-d</option> option which generates
2187 a dump of the decision procedure used to arrive at a conclusion
2188 about which files should be recompiled. Sometimes useful for
2189 tracking down problems with superfluous or missing
2190 recompilations.</para>
2194 <title>A small project</title>
2196 <para>To get started, let us look at the
2197 <filename>Makefile</filename> for an imaginary small
2198 <literal>fptools</literal> project, <literal>small</literal>.
2199 Each project in <literal>fptools</literal> has its own directory
2200 in <constant>FPTOOLS_TOP</constant>, so the
2201 <literal>small</literal> project will have its own directory
2202 <constant>FPOOLS_TOP/small/</constant>. Inside the
2203 <filename>small/</filename> directory there will be a
2204 <filename>Makefile</filename>, looking something like
2207 <indexterm><primary>Makefile, minimal</primary></indexterm>
2210 # Makefile for fptools project "small"
2213 include $(TOP)/mk/boilerplate.mk
2215 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2218 include $(TOP)/target.mk
2221 <para>this <filename>Makefile</filename> has three
2226 <para>The first section includes
2229 One of the most important
2230 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2231 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2236 a file of “boilerplate” code from the level
2237 above (which in this case will be
2238 <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2239 As its name suggests, <filename>boilerplate.mk</filename>
2240 consists of a large quantity of standard
2241 <filename>Makefile</filename> code. We discuss this
2242 boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
2243 <indexterm><primary>include, directive in
2244 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2245 inclusion</primary></indexterm></para>
2247 <para>Before the <literal>include</literal> statement, you
2248 must define the <command>make</command> variable
2249 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2250 to be the directory containing the <filename>mk</filename>
2251 directory in which the <filename>boilerplate.mk</filename>
2252 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2255 include ../mk/boilerplate.mk # NO NO NO
2259 <para>Why? Because the <filename>boilerplate.mk</filename>
2260 file needs to know where it is, so that it can, in turn,
2261 <literal>include</literal> other files. (Unfortunately,
2262 when an <literal>include</literal>d file does an
2263 <literal>include</literal>, the filename is treated relative
2264 to the directory in which <command>gmake</command> is being
2265 run, not the directory in which the
2266 <literal>include</literal>d sits.) In general,
2267 <emphasis>every file <filename>foo.mk</filename> assumes
2269 <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
2270 refers to itself.</emphasis> It is up to the
2271 <filename>Makefile</filename> doing the
2272 <literal>include</literal> to ensure this is the case.</para>
2274 <para>Files intended for inclusion in other
2275 <filename>Makefile</filename>s are written to have the
2276 following property: <emphasis>after
2277 <filename>foo.mk</filename> is <literal>include</literal>d,
2278 it leaves <constant>TOP</constant> containing the same value
2279 as it had just before the <literal>include</literal>
2280 statement</emphasis>. In our example, this invariant
2281 guarantees that the <literal>include</literal> for
2282 <filename>target.mk</filename> will look in the same
2283 directory as that for <filename>boilerplate.mk</filename>.</para>
2287 <para> The second section defines the following standard
2288 <command>make</command> variables:
2289 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2290 (the source files from which is to be built), and
2291 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2292 (the executable binary to be built). We will discuss in
2293 more detail what the “standard variables” are,
2294 and how they affect what happens, in <XRef
2295 LinkEnd="sec-targets">.</para>
2297 <para>The definition for <constant>SRCS</constant> uses the
2298 useful GNU <command>make</command> construct
2299 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2300 which expands to a list of all the files matching the
2301 pattern <literal>pat</literal> in the current directory. In
2302 this example, <constant>SRCS</constant> is set to the list
2303 of all the <filename>.lhs</filename> and
2304 <filename>.c</filename> files in the directory. (Let's
2305 suppose there is one of each, <filename>Foo.lhs</filename>
2306 and <filename>Baz.c</filename>.)</para>
2310 <para>The last section includes a second file of standard
2312 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2313 It contains the rules that tell <command>gmake</command> how
2314 to make the standard targets (<Xref
2315 LinkEnd="sec-standard-targets">). Why, you ask, can't this
2316 standard code be part of
2317 <filename>boilerplate.mk</filename>? Good question. We
2318 discuss the reason later, in <Xref
2319 LinkEnd="sec-boiler-arch">.</para>
2321 <para>You do not <emphasis>have</emphasis> to
2322 <literal>include</literal> the
2323 <filename>target.mk</filename> file. Instead, you can write
2324 rules of your own for all the standard targets. Usually,
2325 though, you will find quite a big payoff from using the
2326 canned rules in <filename>target.mk</filename>; the price
2327 tag is that you have to understand what canned rules get
2328 enabled, and what they do (<Xref
2329 LinkEnd="sec-targets">).</para>
2333 <para>In our example <filename>Makefile</filename>, most of the
2334 work is done by the two <literal>include</literal>d files. When
2335 you say <command>gmake all</command>, the following things
2340 <para><command>gmake</command> figures out that the object
2341 files are <filename>Foo.o</filename> and
2342 <filename>Baz.o</filename>.</para>
2346 <para>It uses a boilerplate pattern rule to compile
2347 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2348 using a Haskell compiler. (Which one? That is set in the
2349 build configuration.)</para>
2353 <para>It uses another standard pattern rule to compile
2354 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2355 using a C compiler. (Ditto.)</para>
2359 <para>It links the resulting <filename>.o</filename> files
2360 together to make <literal>small</literal>, using the Haskell
2361 compiler to do the link step. (Why not use
2362 <command>ld</command>? Because the Haskell compiler knows
2363 what standard libraries to link in. How did
2364 <command>gmake</command> know to use the Haskell compiler to
2365 do the link, rather than the C compiler? Because we set the
2366 variable <constant>HS_PROG</constant> rather than
2367 <constant>C_PROG</constant>.)</para>
2371 <para>All <filename>Makefile</filename>s should follow the above
2372 three-section format.</para>
2376 <title>A larger project</title>
2378 <para>Larger projects are usually structured into a number of
2379 sub-directories, each of which has its own
2380 <filename>Makefile</filename>. (In very large projects, this
2381 sub-structure might be iterated recursively, though that is
2382 rare.) To give you the idea, here's part of the directory
2383 structure for the (rather large) GHC project:</para>
2393 ...source files for documentation...
2396 ...source files for driver...
2399 parser/...source files for parser...
2400 renamer/...source files for renamer...
2404 <para>The sub-directories <filename>docs</filename>,
2405 <filename>driver</filename>, <filename>compiler</filename>, and
2406 so on, each contains a sub-component of GHC, and each has its
2407 own <filename>Makefile</filename>. There must also be a
2408 <filename>Makefile</filename> in
2409 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
2410 It does most of its work by recursively invoking
2411 <command>gmake</command> on the <filename>Makefile</filename>s
2412 in the sub-directories. We say that
2413 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2414 <filename>Makefile</filename></emphasis>, because it does little
2415 except organise its children, while the
2416 <filename>Makefile</filename>s in the sub-directories are all
2417 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2418 principle the sub-directories might themselves contain a
2419 non-leaf <filename>Makefile</filename> and several
2420 sub-sub-directories, but that does not happen in GHC.)</para>
2422 <para>The <filename>Makefile</filename> in
2423 <filename>ghc/compiler</filename> is considered a leaf
2424 <filename>Makefile</filename> even though the
2425 <filename>ghc/compiler</filename> has sub-directories, because
2426 these sub-directories do not themselves have
2427 <filename>Makefile</filename>s in them. They are just used to
2428 structure the collection of modules that make up GHC, but all
2429 are managed by the single <filename>Makefile</filename> in
2430 <filename>ghc/compiler</filename>.</para>
2432 <para>You will notice that <filename>ghc/</filename> also
2433 contains a directory <filename>ghc/mk/</filename>. It contains
2434 GHC-specific <filename>Makefile</filename> boilerplate code.
2435 More precisely:</para>
2439 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2440 at the top of <filename>ghc/Makefile</filename>, and of all
2441 the leaf <filename>Makefile</filename>s in the
2442 sub-directories. It in turn <literal>include</literal>s the
2443 main boilerplate file
2444 <filename>mk/boilerplate.mk</filename>.</para>
2448 <para><filename>ghc/mk/target.mk</filename> is
2449 <literal>include</literal>d at the bottom of
2450 <filename>ghc/Makefile</filename>, and of all the leaf
2451 <filename>Makefile</filename>s in the sub-directories. It
2452 in turn <literal>include</literal>s the file
2453 <filename>mk/target.mk</filename>.</para>
2457 <para>So these two files are the place to look for GHC-wide
2458 customisation of the standard boilerplate.</para>
2461 <sect2 id="sec-boiler-arch">
2462 <title>Boilerplate architecture</title>
2463 <indexterm><primary>boilerplate architecture</primary></indexterm>
2465 <para>Every <filename>Makefile</filename> includes a
2466 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2467 file at the top, and
2468 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2469 file at the bottom. In this section we discuss what is in these
2470 files, and why there have to be two of them. In general:</para>
2474 <para><filename>boilerplate.mk</filename> consists of:</para>
2478 <para><emphasis>Definitions of millions of
2479 <command>make</command> variables</emphasis> that
2480 collectively specify the build configuration. Examples:
2481 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2482 the options to feed to the Haskell compiler;
2483 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2484 the sub-directories to enable within the
2485 <literal>nofib</literal> project;
2486 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2487 the name of the Haskell compiler to use when compiling
2488 GHC in the <literal>ghc</literal> project.</para>
2492 <para><emphasis>Standard pattern rules</emphasis> that
2493 tell <command>gmake</command> how to construct one file
2494 from another.</para>
2498 <para><filename>boilerplate.mk</filename> needs to be
2499 <literal>include</literal>d at the <emphasis>top</emphasis>
2500 of each <filename>Makefile</filename>, so that the user can
2501 replace the boilerplate definitions or pattern rules by
2502 simply giving a new definition or pattern rule in the
2503 <filename>Makefile</filename>. <command>gmake</command>
2504 simply takes the last definition as the definitive one.</para>
2506 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2507 definitions, it is also quite common to
2508 <emphasis>augment</emphasis> them. For example, a
2509 <filename>Makefile</filename> might say:</para>
2515 <para>thereby adding “<option>-O</option>” to
2517 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2521 <para><filename>target.mk</filename> contains
2522 <command>make</command> rules for the standard targets
2523 described in <Xref LinkEnd="sec-standard-targets">. These
2524 rules are selectively included, depending on the setting of
2525 certain <command>make</command> variables. These variables
2526 are usually set in the middle section of the
2527 <filename>Makefile</filename> between the two
2528 <literal>include</literal>s.</para>
2530 <para><filename>target.mk</filename> must be included at the
2531 end (rather than being part of
2532 <filename>boilerplate.mk</filename>) for several tiresome
2538 <para><command>gmake</command> commits target and
2539 dependency lists earlier than it should. For example,
2540 <FIlename>target.mk</FIlename> has a rule that looks
2544 $(HS_PROG) : $(OBJS)
2545 $(HC) $(LD_OPTS) $< -o $@
2548 <para>If this rule was in
2549 <filename>boilerplate.mk</filename> then
2550 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2552 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2553 would not have their final values at the moment
2554 <command>gmake</command> encountered the rule. Alas,
2555 <command>gmake</command> takes a snapshot of their
2556 current values, and wires that snapshot into the rule.
2557 (In contrast, the commands executed when the rule
2558 “fires” are only substituted at the moment
2559 of firing.) So, the rule must follow the definitions
2560 given in the <filename>Makefile</filename> itself.</para>
2564 <para>Unlike pattern rules, ordinary rules cannot be
2565 overriden or replaced by subsequent rules for the same
2566 target (at least, not without an error message).
2567 Including ordinary rules in
2568 <filename>boilerplate.mk</filename> would prevent the
2569 user from writing rules for specific targets in specific
2574 <para>There are a couple of other reasons I've
2575 forgotten, but it doesn't matter too much.</para>
2582 <sect2 id="sec-boiler">
2583 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2584 <indexterm><primary>boilerplate.mk</primary></indexterm>
2586 <para>If you look at
2587 <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
2588 you will find that it consists of the following sections, each
2589 held in a separate file:</para>
2593 <term><filename>config.mk</filename></term>
2594 <indexterm><primary>config.mk</primary></indexterm>
2596 <para>is the build configuration file we discussed at
2597 length in <Xref LinkEnd="sec-build-config">.</para>
2602 <term><filename>paths.mk</filename></term>
2603 <indexterm><primary>paths.mk</primary></indexterm>
2605 <para>defines <command>make</command> variables for
2606 pathnames and file lists. This file contains code for
2607 automatically compiling lists of source files and deriving
2608 lists of object files from those. The results can be
2609 overriden in the <filename>Makefile</filename>, but in
2610 most cases the automatic setup should do the right
2613 <para>The following variables may be set in the
2614 <filename>Makefile</filename> to affect how the automatic
2615 source file search is done:</para>
2619 <term><literal>ALL_DIRS</literal></term>
2620 <indexterm><primary><literal>ALL_DIRS</literal></primary>
2623 <para>Set to a list of directories to search in
2624 addition to the current directory for source
2630 <term><literal>EXCLUDE_SRCS</literal></term>
2631 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2634 <para>Set to a list of source files (relative to the
2635 current directory) to omit from the automatic
2636 search. The source searching machinery is clever
2637 enough to know that if you exclude a source file
2638 from which other sources are derived, then the
2639 derived sources should also be excluded. For
2640 example, if you set <literal>EXCLUDED_SRCS</literal>
2641 to include <filename>Foo.y</filename>, then
2642 <filename>Foo.hs</filename> will also be
2648 <term><literal>EXTRA_SRCS</literal></term>
2649 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2652 <para>Set to a list of extra source files (perhaps
2653 in directories not listed in
2654 <literal>ALL_DIRS</literal>) that should be
2660 <para>The results of the automatic source file search are
2661 placed in the following make variables:</para>
2665 <term><literal>SRCS</literal></term>
2666 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2668 <para>All source files found, sorted and without
2669 duplicates, including those which might not exist
2670 yet but will be derived from other existing sources.
2671 <literal>SRCS</literal> <emphasis>can</emphasis> be
2672 overriden if necessary, in which case the variables
2673 below will follow suit.</para>
2678 <term><literal>HS_SRCS</literal></term>
2679 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2681 <para>all Haskell source files in the current
2682 directory, including those derived from other source
2683 files (eg. Happy sources also give rise to Haskell
2689 <term><literal>HS_OBJS</literal></term>
2690 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2692 <para>Object files derived from
2693 <literal>HS_SRCS</literal>.</para>
2698 <term><literal>HS_IFACES</literal></term>
2699 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2701 <para>Interface files (<literal>.hi</literal> files)
2702 derived from <literal>HS_SRCS</literal>.</para>
2707 <term><literal>C_SRCS</literal></term>
2708 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2710 <para>All C source files found.</para>
2715 <term><literal>C_OBJS</literal></term>
2716 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2718 <para>Object files derived from
2719 <literal>C_SRCS</literal>.</para>
2724 <term><literal>SCRIPT_SRCS</literal></term>
2725 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2727 <para>All script source files found
2728 (<literal>.lprl</literal> files).</para>
2733 <term><literal>SCRIPT_OBJS</literal></term>
2734 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2736 <para><quote>object</quote> files derived from
2737 <literal>SCRIPT_SRCS</literal>
2738 (<literal>.prl</literal> files).</para>
2743 <term><literal>HSC_SRCS</literal></term>
2744 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2746 <para>All <literal>hsc2hs</literal> source files
2747 (<literal>.hsc</literal> files).</para>
2752 <term><literal>HAPPY_SRCS</literal></term>
2753 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2755 <para>All <literal>happy</literal> source files
2756 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2761 <term><literal>OBJS</literal></term>
2762 <indexterm><primary>OBJS</primary></indexterm>
2764 <para>the concatenation of
2765 <literal>$(HS_OBJS)</literal>,
2766 <literal>$(C_OBJS)</literal>, and
2767 <literal>$(SCRIPT_OBJS)</literal>.</para>
2772 <para>Any or all of these definitions can easily be
2773 overriden by giving new definitions in your
2774 <filename>Makefile</filename>.</para>
2776 <para>What, exactly, does <filename>paths.mk</filename>
2777 consider a <quote>source file</quote> to be? It's based
2778 on the file's suffix (e.g. <filename>.hs</filename>,
2779 <filename>.lhs</filename>, <filename>.c</filename>,
2780 <filename>.hy</filename>, etc), but this is the kind of
2781 detail that changes, so rather than enumerate the source
2782 suffices here the best thing to do is to look in
2783 <filename>paths.mk</filename>.</para>
2788 <term><filename>opts.mk</filename></term>
2789 <indexterm><primary>opts.mk</primary></indexterm>
2791 <para>defines <command>make</command> variables for option
2792 strings to pass to each program. For example, it defines
2793 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2794 the option strings to pass to the Haskell compiler. See
2795 <Xref LinkEnd="sec-suffix">.</para>
2800 <term><filename>suffix.mk</filename></term>
2801 <indexterm><primary>suffix.mk</primary></indexterm>
2803 <para>defines standard pattern rules—see <Xref
2804 LinkEnd="sec-suffix">.</para>
2809 <para>Any of the variables and pattern rules defined by the
2810 boilerplate file can easily be overridden in any particular
2811 <filename>Makefile</filename>, because the boilerplate
2812 <literal>include</literal> comes first. Definitions after this
2813 <literal>include</literal> directive simply override the default
2814 ones in <filename>boilerplate.mk</filename>.</para>
2817 <sect2 id="sec-suffix">
2818 <title>Pattern rules and options</title>
2819 <indexterm><primary>Pattern rules</primary></indexterm>
2822 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2823 defines standard <emphasis>pattern rules</emphasis> that say how
2824 to build one kind of file from another, for example, how to
2825 build a <filename>.o</filename> file from a
2826 <filename>.c</filename> file. (GNU <command>make</command>'s
2827 <emphasis>pattern rules</emphasis> are more powerful and easier
2828 to use than Unix <command>make</command>'s <emphasis>suffix
2829 rules</emphasis>.)</para>
2831 <para>Almost all the rules look something like this:</para>
2836 $(CC) $(CC_OPTS) -c $< -o $@
2839 <para>Here's how to understand the rule. It says that
2840 <emphasis>something</emphasis><filename>.o</filename> (say
2841 <filename>Foo.o</filename>) can be built from
2842 <emphasis>something</emphasis><filename>.c</filename>
2843 (<filename>Foo.c</filename>), by invoking the C compiler (path
2844 name held in <constant>$(CC)</constant>), passing to it
2845 the options <constant>$(CC_OPTS)</constant> and
2846 the rule's dependent file of the rule
2847 <literal>$<</literal> (<filename>Foo.c</filename> in
2848 this case), and putting the result in the rule's target
2849 <literal>$@</literal> (<filename>Foo.o</filename> in this
2852 <para>Every program is held in a <command>make</command>
2853 variable defined in <filename>mk/config.mk</filename>—look
2854 in <filename>mk/config.mk</filename> for the complete list. One
2855 important one is the Haskell compiler, which is called
2856 <constant>$(HC)</constant>.</para>
2858 <para>Every program's options are are held in a
2859 <command>make</command> variables called
2860 <constant><prog>_OPTS</constant>. the
2861 <constant><prog>_OPTS</constant> variables are
2862 defined in <filename>mk/opts.mk</filename>. Almost all of them
2863 are defined like this:</para>
2866 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
2869 <para>The four variables from which
2870 <constant>CC_OPTS</constant> is built have the following
2875 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
2877 <para>options passed to all C compilations.</para>
2882 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
2884 <para>options passed to C compilations for way
2885 <literal><way></literal>. For example,
2886 <constant>WAY_mp_CC_OPTS</constant>
2887 gives options to pass to the C compiler when compiling way
2888 <literal>mp</literal>. The variable
2889 <constant>WAY_CC_OPTS</constant> holds
2890 options to pass to the C compiler when compiling the
2891 standard way. (<Xref LinkEnd="sec-ways"> dicusses
2892 multi-way compilation.)</para>
2897 <term><constant><module>_CC_OPTS</constant>:</term>
2899 <para>options to pass to the C compiler that are specific
2900 to module <literal><module></literal>. For example,
2901 <constant>SMap_CC_OPTS</constant> gives the
2902 specific options to pass to the C compiler when compiling
2903 <filename>SMap.c</filename>.</para>
2908 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
2910 <para>extra options to pass to all C compilations. This
2911 is intended for command line use, thus:</para>
2914 gmake libHS.a EXTRA_CC_OPTS="-v"
2921 <sect2 id="sec-targets">
2922 <title>The main <filename>mk/target.mk</filename> file</title>
2923 <indexterm><primary>target.mk</primary></indexterm>
2925 <para><filename>target.mk</filename> contains canned rules for
2926 all the standard targets described in <Xref
2927 LinkEnd="sec-standard-targets">. It is complicated by the fact
2928 that you don't want all of these rules to be active in every
2929 <filename>Makefile</filename>. Rather than have a plethora of
2930 tiny files which you can include selectively, there is a single
2931 file, <filename>target.mk</filename>, which selectively includes
2932 rules based on whether you have defined certain variables in
2933 your <filename>Makefile</filename>. This section explains what
2934 rules you get, what variables control them, and what the rules
2935 do. Hopefully, you will also get enough of an idea of what is
2936 supposed to happen that you can read and understand any weird
2937 special cases yourself.</para>
2941 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
2943 <para>If <constant>HS_PROG</constant> is defined,
2944 you get rules with the following targets:</para>
2948 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
2950 <para>itself. This rule links
2951 <constant>$(OBJS)</constant> with the Haskell
2952 runtime system to get an executable called
2953 <constant>$(HS_PROG)</constant>.</para>
2958 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
2961 <constant>$(HS_PROG)</constant> in
2962 <constant>$(bindir)</constant>.</para>
2971 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
2973 <para>is similar to <constant>HS_PROG</constant>,
2974 except that the link step links
2975 <constant>$(C_OBJS)</constant> with the C
2976 runtime system.</para>
2981 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
2983 <para>is similar to <constant>HS_PROG</constant>,
2984 except that it links
2985 <constant>$(LIB_OBJS)</constant> to make the
2986 library archive <constant>$(LIBRARY)</constant>,
2987 and <literal>install</literal> installs it in
2988 <constant>$(libdir)</constant>.</para>
2993 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
2995 <para>…</para>
3000 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3002 <para>…</para>
3007 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3009 <para>If <constant>HS_SRCS</constant> is defined
3010 and non-empty, a rule for the target
3011 <literal>depend</literal> is included, which generates
3012 dependency information for Haskell programs. Similarly
3013 for <constant>C_SRCS</constant>.</para>
3018 <para>All of these rules are “double-colon” rules,
3022 install :: $(HS_PROG)
3023 ...how to install it...
3026 <para>GNU <command>make</command> treats double-colon rules as
3027 separate entities. If there are several double-colon rules for
3028 the same target it takes each in turn and fires it if its
3029 dependencies say to do so. This means that you can, for
3030 example, define both <constant>HS_PROG</constant> and
3031 <constant>LIBRARY</constant>, which will generate two rules for
3032 <literal>install</literal>. When you type <command>gmake
3033 install</command> both rules will be fired, and both the program
3034 and the library will be installed, just as you wanted.</para>
3037 <sect2 id="sec-subdirs">
3038 <title>Recursion</title>
3039 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3040 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3042 <para>In leaf <filename>Makefile</filename>s the variable
3043 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3044 is undefined. In non-leaf <filename>Makefile</filename>s,
3045 <constant>SUBDIRS</constant> is set to the list of
3046 sub-directories that contain subordinate
3047 <filename>Makefile</filename>s. <emphasis>It is up to you to
3048 set <constant>SUBDIRS</constant> in the
3049 <filename>Makefile</filename>.</emphasis> There is no automation
3050 here—<constant>SUBDIRS</constant> is too important to
3053 <para>When <constant>SUBDIRS</constant> is defined,
3054 <filename>target.mk</filename> includes a rather neat rule for
3055 the standard targets (<Xref LinkEnd="sec-standard-targets"> that
3056 simply invokes <command>make</command> recursively in each of
3057 the sub-directories.</para>
3059 <para><emphasis>These recursive invocations are guaranteed to
3060 occur in the order in which the list of directories is specified
3061 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3062 be important. For example, when you say <command>gmake
3063 boot</command> it can be important that the recursive invocation
3064 of <command>make boot</command> is done in one sub-directory
3065 (the include files, say) before another (the source files).
3066 Generally, put the most independent sub-directory first, and the
3067 most dependent last.</para>
3070 <sect2 id="sec-ways">
3071 <title>Way management</title>
3072 <indexterm><primary>way management</primary></indexterm>
3074 <para>We sometimes want to build essentially the same system in
3075 several different “ways”. For example, we want to build GHC's
3076 <literal>Prelude</literal> libraries with and without profiling,
3077 so that there is an appropriately-built library archive to link
3078 with when the user compiles his program. It would be possible
3079 to have a completely separate build tree for each such “way”,
3080 but it would be horribly bureaucratic, especially since often
3081 only parts of the build tree need to be constructed in multiple
3085 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3086 contains some clever magic to allow you to build several
3087 versions of a system; and to control locally how many versions
3088 are built and how they differ. This section explains the
3091 <para>The files for a particular way are distinguished by
3092 munging the suffix. The <quote>normal way</quote> is always
3093 built, and its files have the standard suffices
3094 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3095 In addition, you can build one or more extra ways, each
3096 distinguished by a <emphasis>way tag</emphasis>. The object
3097 files and interface files for one of these extra ways are
3098 distinguished by their suffix. For example, way
3099 <literal>mp</literal> has files
3100 <filename>.mp_o</filename> and
3101 <filename>.mp_hi</filename>. Library archives have their
3102 way tag the other side of the dot, for boring reasons; thus,
3103 <filename>libHS_mp.a</filename>.</para>
3105 <para>A <command>make</command> variable called
3106 <constant>way</constant> holds the current way tag.
3107 <emphasis><constant>way</constant> is only ever set on the
3108 command line of <command>gmake</command></emphasis> (usually in
3109 a recursive invocation of <command>gmake</command> by the
3110 system). It is never set inside a
3111 <filename>Makefile</filename>. So it is a global constant for
3112 any one invocation of <command>gmake</command>. Two other
3113 <command>make</command> variables,
3114 <constant>way_</constant> and
3115 <constant>_way</constant> are immediately derived from
3116 <constant>$(way)</constant> and never altered. If
3117 <constant>way</constant> is not set, then neither are
3118 <constant>way_</constant> and
3119 <constant>_way</constant>, and the invocation of
3120 <command>make</command> will build the <quote>normal
3121 way</quote>. If <constant>way</constant> is set, then the other
3122 two variables are set in sympathy. For example, if
3123 <constant>$(way)</constant> is “<literal>mp</literal>”,
3124 then <constant>way_</constant> is set to
3125 “<literal>mp_</literal>” and
3126 <constant>_way</constant> is set to
3127 “<literal>_mp</literal>”. These three variables are
3128 then used when constructing file names.</para>
3130 <para>So how does <command>make</command> ever get recursively
3131 invoked with <constant>way</constant> set? There are two ways
3132 in which this happens:</para>
3136 <para>For some (but not all) of the standard targets, when
3137 in a leaf sub-directory, <command>make</command> is
3138 recursively invoked for each way tag in
3139 <constant>$(WAYS)</constant>. You set
3140 <constant>WAYS</constant> in the
3141 <filename>Makefile</filename> to the list of way tags you
3142 want these targets built for. The mechanism here is very
3143 much like the recursive invocation of
3144 <command>make</command> in sub-directories (<Xref
3145 LinkEnd="sec-subdirs">). It is up to you to set
3146 <constant>WAYS</constant> in your
3147 <filename>Makefile</filename>; this is how you control what
3148 ways will get built.</para>
3152 <para>For a useful collection of targets (such as
3153 <filename>libHS_mp.a</filename>,
3154 <filename>Foo.mp_o</filename>) there is a rule which
3155 recursively invokes <command>make</command> to make the
3156 specified target, setting the <constant>way</constant>
3157 variable. So if you say <command>gmake
3158 Foo.mp_o</command> you should see a recursive
3159 invocation <command>gmake Foo.mp_o way=mp</command>,
3160 and <emphasis>in this recursive invocation the pattern rule
3161 for compiling a Haskell file into a <filename>.o</filename>
3162 file will match</emphasis>. The key pattern rules (in
3163 <filename>suffix.mk</filename>) look like this:
3167 $(HC) $(HC_OPTS) $< -o $@
3174 <para>You can invoke <command>make</command> with a
3175 particular <literal>way</literal> setting yourself, in order
3176 to build files related to a particular
3177 <literal>way</literal> in the current directory. eg.
3183 will build files for the profiling way only in the current
3190 <title>When the canned rule isn't right</title>
3192 <para>Sometimes the canned rule just doesn't do the right thing.
3193 For example, in the <literal>nofib</literal> suite we want the
3194 link step to print out timing information. The thing to do here
3195 is <emphasis>not</emphasis> to define
3196 <constant>HS_PROG</constant> or
3197 <constant>C_PROG</constant>, and instead define a special
3198 purpose rule in your own <filename>Makefile</filename>. By
3199 using different variable names you will avoid the canned rules
3200 being included, and conflicting with yours.</para>
3204 <sect1 id="sec-porting-ghc">
3205 <title>Porting GHC</title>
3207 <para>This section describes how to port GHC to a currenly
3208 unsupported platform. There are two distinct
3209 possibilities:</para>
3213 <para>The hardware architecture for your system is already
3214 supported by GHC, but you're running an OS that isn't
3215 supported (or perhaps has been supported in the past, but
3216 currently isn't). This is the easiest type of porting job,
3217 but it still requires some careful bootstrapping. Proceed to
3218 <xref linkend="sec-booting-from-hc">.</para>
3222 <para>Your system's hardware architecture isn't supported by
3223 GHC. This will be a more difficult port (though by comparison
3224 perhaps not as difficult as porting gcc). Proceed to <xref
3225 linkend="unregisterised-porting">.</para>
3229 <sect2 id="sec-booting-from-hc">
3230 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3232 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3233 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3234 <indexterm><primary>porting GHC</primary></indexterm>
3236 <para>Bootstrapping GHC on a system without GHC already
3237 installed is achieved by taking the intermediate C files (known
3238 as HC files) from a GHC compilation on a supported system to the
3239 target machine, and compiling them using gcc to get a working
3242 <para><emphasis>NOTE: GHC version 5.xx is significantly harder
3243 to bootstrap from C than previous versions. We recommend
3244 starting from version 4.08.2 if you need to bootstrap in this
3245 way.</emphasis></para>
3247 <para>HC files are architecture-dependent (but not
3248 OS-dependent), so you have to get a set that were generated on
3249 similar hardware. There may be some supplied on the GHC
3250 download page, otherwise you'll have to compile some up
3251 yourself, or start from <emphasis>unregisterised</emphasis> HC
3252 files - see <xref linkend="unregisterised-porting">.</para>
3254 <para>The following steps should result in a working GHC build
3255 with full libraries:</para>
3259 <para>Unpack the HC files on top of a fresh source tree
3260 (make sure the source tree version matches the version of
3261 the HC files <emphasis>exactly</emphasis>!). This will
3262 place matching <filename>.hc</filename> files next to the
3263 corresponding Haskell source (<filename>.hs</filename> or
3264 <filename>.lhs</filename>) in the compiler subdirectory
3265 <filename>ghc/compiler</filename> and in the libraries
3266 (<filename>ghc/lib</filename>, and subdirectories of
3267 <filename>hslibs</filename>).</para>
3271 <para>The actual build process is fully automated by the
3272 <filename>hc-build</filename> script located in the
3273 <filename>distrib</filename> directory. If you eventually
3274 want to install GHC into the directory
3275 <replaceable>dir</replaceable>, the following
3276 command will execute the whole build process (it won't
3277 install yet):</para>
3280 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3282 <indexterm><primary>--hc-build</primary></indexterm>
3284 <para>By default, the installation directory is
3285 <filename>/usr/local</filename>. If that is what you want,
3286 you may omit the argument to <filename>hc-build</filename>.
3287 Generally, any option given to <filename>hc-build</filename>
3288 is passed through to the configuration script
3289 <filename>configure</filename>. If
3290 <filename>hc-build</filename> successfully completes the
3291 build process, you can install the resulting system, as
3301 <sect2 id="unregisterised-porting">
3302 <title>Porting GHC to a new architecture</title>
3304 <para>The first step in porting to a new architecture is to get
3305 an <firstterm>unregisterised</firstterm> build working. An
3306 unregisterised build is one that compiles via vanilla C only.
3307 By contrast, a registerised build uses the following
3308 architecture-specific hacks for speed:</para>
3312 <para>Global register variables: certain abstract machine
3313 <quote>registers</quote> are mapped to real machine
3314 registers, depending on how many machine registers are
3316 <filename>ghc/includes/MachRegs.h</filename>).</para>
3320 <para>Assembly-mangling: when compiling via C, we feed the
3321 assembly generated by gcc though a Perl script known as the
3322 <firstterm>mangler</firstterm> (see
3323 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3324 mangler rearranges the assembly to support tail-calls and
3325 various other optimisations.</para>
3329 <para>In an unregisterised build, neither of these hacks are
3330 used — the idea is that the C code generated by the
3331 compiler should compile using gcc only. The lack of these
3332 optimisations costs about a factor of two in performance, but
3333 since unregisterised compilation is usually just a step on the
3334 way to a full registerised port, we don't mind too much.</para>
3337 <title>Building an unregisterised port</title>
3339 <para>The first step is to get some unregisterised HC files.
3340 Either (a) download them from the GHC site (if there are
3341 some available for the right version of GHC), or
3342 (b) build them yourself on any machine with a working
3343 GHC. If at all possible this should be a machine with the
3344 same word size as the target.</para>
3346 <para>There is a script available which should automate the
3347 process of doing the 2-stage bootstrap necessary to get the
3348 unregisterised HC files - it's available in <ulink
3349 url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
3352 <para>Now take these unregisterised HC files to the target
3353 platform and bootstrap a compiler from them as per the
3354 instructions in <xref linkend="sec-booting-from-hc">. In
3355 <filename>build.mk</filename>, you need to tell the build
3356 system that the compiler you're building is
3357 (a) unregisterised itself, and (b) builds
3358 unregisterised binaries. This varies depending on the GHC
3359 version you're bootstraping:</para>
3362 # build.mk for GHC 4.08.x
3363 GhcWithRegisterised=NO
3367 # build.mk for GHC 5.xx
3368 GhcUnregisterised=YES
3371 <para>Version 5.xx only: use the option
3372 <option>--enable-hc-boot-unregisterised</option> instead of
3373 <option>--enable-hc-boot</option> when running
3374 <filename>./configure</filename>.</para>
3376 <para>The build may not go through cleanly. We've tried to
3377 stick to writing portable code in most parts of the compiler,
3378 so it should compile on any POSIXish system with gcc, but in
3379 our experience most systems differ from the standards in one
3380 way or another. Deal with any problems as they arise - if you
3381 get stuck, ask the experts on
3382 <email>glasgow-haskell-users@haskell.org</email>.</para>
3384 <para>Once you have the unregisterised compiler up and
3385 running, you can use it to start a registerised port. The
3386 following sections describe the various parts of the system
3387 that will need architecture-specific tweaks in order to get a
3388 registerised build going.</para>
3390 <para>Lots of useful information about the innards of GHC is
3391 available in the <ulink
3392 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3393 Commentary</ulink>, which might be helpful if you run into
3394 some code which needs tweaking for your system.</para>
3398 <title>Porting the RTS</title>
3400 <para>The following files need architecture-specific code for a
3401 registerised build:</para>
3405 <term><filename>ghc/includes/MachRegs.h</filename></term>
3406 <indexterm><primary><filename>MachRegs.h</filename></primary>
3409 <para>Defines the STG-register to machine-register
3410 mapping. You need to know your platform's C calling
3411 convention, and which registers are generally available
3412 for mapping to global register variables. There are
3413 plenty of useful comments in this file.</para>
3417 <term><filename>ghc/includes/TailCalls.h</filename></term>
3418 <indexterm><primary><filename>TailCalls.h</filename></primary>
3421 <para>Macros that cooperate with the mangler (see <xref
3422 linkend="sec-mangler">) to make proper tail-calls
3427 <term><filename>ghc/rts/Adjustor.c</filename></term>
3428 <indexterm><primary><filename>Adjustor.c</filename></primary>
3432 <literal>foreign import "wrapper"</literal>
3434 <literal>foreign export dynamic</literal>).
3435 Not essential for getting GHC bootstrapped, so this file
3436 can be deferred until later if necessary.</para>
3440 <term><filename>ghc/rts/StgCRun.c</filename></term>
3441 <indexterm><primary><filename>StgCRun.c</filename></primary>
3444 <para>The little assembly layer between the C world and
3445 the Haskell world. See the comments and code for the
3446 other architectures in this file for pointers.</para>
3450 <term><filename>ghc/rts/MBlock.h</filename></term>
3451 <term><filename>ghc/rts/MBlock.c</filename></term>
3452 <indexterm><primary><filename>MBlock.h</filename></primary>
3454 <indexterm><primary><filename>MBlock.c</filename></primary>
3457 <para>These files are really OS-specific rather than
3458 architecture-specific. In <filename>MBlock.h</filename>
3459 is specified the absolute location at which the RTS
3460 should try to allocate memory on your platform (try to
3461 find an area which doesn't conflict with code or dynamic
3462 libraries). In <filename>Mblock.c</filename> you might
3463 need to tweak the call to <literal>mmap()</literal> for
3470 <sect3 id="sec-mangler">
3471 <title>The mangler</title>
3473 <para>The mangler is an evil Perl-script that rearranges the
3474 assembly code output from gcc to do two main things:</para>
3478 <para>Remove function prologues and epilogues, and all
3479 movement of the C stack pointer. This is to support
3480 tail-calls: every code block in Haskell code ends in an
3481 explicit jump, so we don't want the C-stack overflowing
3482 while we're jumping around between code blocks.</para>
3485 <para>Move the <firstterm>info table</firstterm> for a
3486 closure next to the entry code for that closure. In
3487 unregisterised code, info tables contain a pointer to the
3488 entry code, but in registerised compilation we arrange
3489 that the info table is shoved right up against the entry
3490 code, and addressed backwards from the entry code pointer
3491 (this saves a word in the info table and an extra
3492 indirection when jumping to the closure entry
3497 <para>The mangler is abstracted to a certain extent over some
3498 architecture-specific things such as the particular assembler
3499 directives used to herald symbols. Take a look at the
3500 definitions for other architectures and use these as a
3501 starting point.</para>
3505 <title>The native code generator</title>
3507 <para>The native code generator isn't essential to getting a
3508 registerised build going, but it's a desirable thing to have
3509 because it can cut compilation times in half. The native code
3510 generator is described in some detail in the <ulink
3511 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3512 commentary</ulink>.</para>
3518 <para>To support GHCi, you need to port the dynamic linker
3519 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
3520 currently supports the ELF and PEi386 object file formats - if
3521 your platform uses one of these then you probably don't have
3522 to do anything except fiddle with the
3523 <literal>#ifdef</literal>s at the top of
3524 <filename>Linker.c</filename> to tell it about your OS.</para>
3526 <para>If your system uses a different object file format, then
3527 you have to write a linker — good luck!</para>
3533 <sect1 id="sec-build-pitfalls">
3534 <title>Known pitfalls in building Glasgow Haskell
3536 <indexterm><primary>problems, building</primary></indexterm>
3537 <indexterm><primary>pitfalls, in building</primary></indexterm>
3538 <indexterm><primary>building pitfalls</primary></indexterm></title>
3541 WARNINGS about pitfalls and known “problems”:
3550 One difficulty that comes up from time to time is running out of space
3551 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
3552 compensate for the vagaries of different sysadmin approaches to temp
3554 <indexterm><primary>tmp, running out of space in</primary></indexterm>
3556 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
3557 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
3560 The best way around it is to say
3563 export TMPDIR=<dir>
3566 in your <filename>build.mk</filename> file.
3567 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
3576 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
3577 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
3585 When compiling via C, you'll sometimes get “warning: assignment from
3586 incompatible pointer type” out of GCC. Harmless.
3593 Similarly, <command>ar</command>chiving warning messages like the following are not
3597 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
3598 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
3608 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
3609 get an “Out of heap space” error message. These can vary with the
3610 vagaries of different systems, it seems. The solution is simple:
3617 If you're compiling with GHC 4.00 or later, then the
3618 <emphasis>maximum</emphasis> heap size must have been reached. This
3619 is somewhat unlikely, since the maximum is set to 64M by default.
3620 Anyway, you can raise it with the
3621 <option>-optCrts-M<size></option> flag (add this flag to
3622 <constant><module>_HC_OPTS</constant>
3623 <command>make</command> variable in the appropriate
3624 <filename>Makefile</filename>).
3631 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
3640 and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
3641 <constant><module>_HC_OPTS</constant>.)
3643 Alternatively, just cut to the chase:
3647 % make EXTRA_HC_OPTS=-optCrts-M128M
3656 If you try to compile some Haskell, and you get errors from GCC about
3657 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
3658 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
3660 As <command>fixincludes</command> is now automagically run as part of GCC installation,
3661 this bug also suggests that you have an old GCC.
3669 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
3673 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
3674 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
3676 ? # or, on some machines: ar s $i
3681 We'd be interested to know if this is still necessary.
3689 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
3690 a bit from one Unix to another. One particular gotcha is macro calls
3695 SLIT("Hello, world")
3699 Some <command>cpp</command>s treat the comma inside the string as separating two macro
3700 arguments, so you get
3704 :731: macro `SLIT' used with too many (2) args
3708 Alas, <command>cpp</command> doesn't tell you the offending file!
3710 Workaround: don't put weird things in string args to <command>cpp</command> macros.
3721 <Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
3724 This section summarises how to get the utilities you need on your
3725 Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
3726 installing and running GHC may be found in the user guide. In general,
3727 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
3728 You should read the GHC installation guide sections on Windows (in the user
3729 guide) before continuing to read these notes.
3733 <Sect2><Title>Installing and configuring Cygwin</Title>
3735 <para>You don't need Cygwin to <emphasis>use</emphasis> GHC, but you do need it to <emphasis>build</emphasis> GHC.</para>
3737 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
3738 The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
3739 Both <command>cvs</command> and <command>ssh</command>
3740 come with Cygwin, but you'll need them, so make sure you select them when running
3741 the Cygwin installer.
3744 <para> Now set the following user environment variables:
3747 <listitem><para> Add <filename>c:/cygwin/bin</filename> to your
3748 <constant>PATH</constant></para></listitem>
3752 Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
3753 don't do this you get very weird messages when you type
3754 <Command>make</Command>, such as:
3756 /c: /c: No such file or directory
3761 <listitem><para> Set <constant>SHELL</constant> to
3762 <Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
3763 <constant>SHELL</constant> is what you get.
3766 <listitem><para> Set <constant>HOME</constant> to point to your
3767 home directory. This is where, for example,
3768 <command>bash</command> will look for your <filename>.bashrc</filename>
3769 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
3775 There are a few other things to do:
3779 Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
3780 (and similarly for <Command>bash</Command>). Notice the hardwired path!
3781 So you need to ensure that your <Filename>/bin</Filename> directory has the following
3784 <listitem> <para><Command>sh</Command></para></listitem>
3785 <listitem> <para><Command>perl</Command></para></listitem>
3786 <listitem> <para><Command>cat</Command></para></listitem>
3788 All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
3789 installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
3790 <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
3791 (You can discover where your Cygwin
3792 root directory <Filename>/</Filename> is by typing <Command>mount</Command>).
3793 Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
3794 directory, there's no need to copy anything.
3800 By default, cygwin provides the command shell <filename>ash</filename>
3801 as <filename>sh.exe</filename>. It has a couple of 'issues', so
3802 in your <filename>/bin</filename> directory, make sure that <filename>
3803 bash.exe</filename> is also provided as <filename>sh.exe</filename>
3804 (i.e. overwrite the old <filename>sh.exe</filename> with a copy of
3805 <filename>bash.exe</filename>).
3811 <para>Finally, here are some things to be aware of when using Cygwin:
3813 <listitem> <para>Cygwin doesn't deal well with filenames that include
3814 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
3818 <listitem> <para> Cygwin implements a symbolic link as a text file with some
3819 magical text in it. So other programs that don't use Cygwin's
3820 I/O libraries won't recognise such files as symlinks.
3821 In particular, programs compiled by GHC are meant to be runnable
3822 without having Cygwin, so they don't use the Cygwin library, so
3823 they don't recognise symlinks.
3827 Win32 has a <command>find</command> command which is not the same as Cygwin's find.
3828 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
3829 before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
3830 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
3831 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
3838 <Sect2><Title>Other things you need to install</Title>
3840 <para>You have to install the following other things to build GHC:
3844 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
3845 This is what you will use to compile GHC. Add it in your
3846 <constant>PATH</constant>: the installer tells you the path element
3847 you need to add upon completion.
3853 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
3854 Happy is a parser generator used to compile the Haskell grammar. Add it in your
3855 <constant>PATH</constant>.
3861 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
3862 generate code, so you have to install that. Just pick up a mingw bundle at
3863 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
3864 We install it in <filename>c:/mingw</filename>.
3870 <para> Finally, check out a copy of GHC sources from
3871 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
3878 <Sect2><Title>Building GHC</Title>
3881 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
3882 the bullets below only tell
3883 you about Windows-specific wrinkles.</para>
3887 Run <Command>autoconf</Command> both in <filename>fptools</filename>
3888 and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
3889 get an error when you run <filename>./configure</filename>:
3892 creating mk/config.h
3893 mk/config.h is unchanged
3895 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
3896 ./configure: ./configure: No such file or directory
3897 configure: error: ./configure failed for ghc
3904 You either need to add <filename>ghc</filename> to your
3905 <constant>PATH</constant> before you invoke
3906 <Command>configure</Command>, or use the <Command>configure</Command>
3907 option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
3913 After <command>autoconf</command> run <command>./configure</command> in
3914 <filename>fptools/</filename> thus:
3917 ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc
3920 Both these options are important! It's possible to get into
3921 trouble using the wrong C compiler!
3925 <listitem><para> Do not attempt to build the documentation.
3926 It needs all kinds of wierd Jade stuff that we haven't worked out for
3927 Win32.</para></listitem>
projects / ghc-hetmet.git / blob