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 <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
250 <para>Send a message to to the CVS repository
251 administrator (currently Jeff Lewis
252 <email>jeff@galconn.com</email>), containing:</para>
255 <para>Your desired user-name.</para>
258 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
259 <literal>.ssh/identity.pub</literal>).</para>
262 <para>He will set up your account.</para>
266 <para>Set the following environment variables:</para>
270 <constant>$HOME</constant>: points to your home directory. This is where CVS
271 will look for its <filename>.cvsrc</filename> file.
277 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
279 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
280 <literal>ssh</literal> assumes that your CVS client
281 understands how to execute shell script
282 ("#!"s,really), which is what
283 <literal>ssh</literal> is. This may not be the case on
284 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
285 <literal>ssh1</literal>.</para>
289 <para><literal>$CVSROOT</literal> to
290 <literal>:ext:</literal><replaceable>your-username</replaceable>
291 <literal>@cvs.haskell.org:/home/cvs/root</literal>
292 where <replaceable>your-username</replaceable> is your user name on
293 <literal>cvs.haskell.org</literal>.
295 <para>The <literal>CVSROOT</literal> environment variable will
296 be recorded in the checked-out tree, so you don't need to set
297 this every time. </para>
303 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
304 if you want to use an Emacs buffer for typing in those long commit messages.
310 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
311 set this to point to <filename>bash.exe</filename>.
322 Put the following in <filename>$HOME/.cvsrc</filename>:
333 These are the default options for the specified CVS commands,
334 and represent better defaults than the usual ones. (Feel
335 free to change them.)
339 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
340 the 8.3 DOS filesystem, but that restriction should have
341 been lifted by now (i.e., you're using VFAT or later filesystems.) If
342 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
350 <para>[Experts.] Once your account is set up, you can get
351 access from other machines without bothering Jeff, thus:</para>
354 <para>Generate a public/private key pair on the new
358 <para>Use ssh to log in to
359 <literal>cvs.haskell.org</literal>, from your old
363 <para>Add the public key for the new machine to the file
364 <literal>$HOME/ssh/authorized_keys</literal> on
365 <literal>cvs.haskell.org</literal>.
366 (<literal>authorized_keys2</literal>, I think, for Version
370 <para>Make sure that the new version of
371 <literal>authorized_keys</literal> still has 600 file
380 <sect2 id="cvs-first">
381 <title>Checking Out a Source Tree</title>
385 <para>Make sure you set your <literal>CVSROOT</literal>
386 environment variable according to either of the remote
387 methods above. The Approved Way to check out a source tree
388 is as follows:</para>
391 $ cvs checkout fpconfig
394 <para>At this point you have a new directory called
395 <literal>fptools</literal> which contains the basic stuff
396 for the fptools suite, including the configuration files and
397 some other junk. </para>
399 <para>[Windows users.] The following messages appear to be harmless:
401 setsockopt IPTOS_LOWDELAY: Invalid argument
402 setsockopt IPTOS_THROUGHPUT: Invalid argument
407 <para>You can call the fptools directory whatever you like,
408 CVS won't mind: </para>
411 $ mv fptools <replaceable>directory</replaceable>
414 <para> NB: after you've read the CVS manual you might be
415 tempted to try</para>
417 $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
420 <para>instead of checking out <literal>fpconfig</literal>
421 and then renaming it. But this doesn't work, and will
422 result in checking out the entire repository instead of just
423 the <literal>fpconfig</literal> bit.</para>
425 $ cd <replaceable>directory</replaceable>
426 $ cvs checkout ghc hslibs libraries
429 <para>The second command here checks out the relevant
430 modules you want to work on. For a GHC build, for instance,
431 you need at least the <literal>ghc</literal>,
432 <literal>hslibs</literal> and <literal>libraries</literal>
433 modules (for a full list of the projects available, see
434 <xref linkend="projects">).</para>
436 <para>Remember that if you do not have
437 <literal>happy</literal> and/or <literal>Alex</literal>
438 installed, you need to check them out as well.</para>
443 <sect2 id="cvs-committing">
444 <title>Committing Changes</title>
446 <para>This is only if you have read-write access to the
447 repository. For anoncvs users, CVS will issue a "read-only
448 repository" error if you try to commit changes.</para>
452 <para>Build the software, if necessary. Unless you're just
453 working on documentation, you'll probably want to build the
454 software in order to test any changes you make.</para>
458 <para>Make changes. Preferably small ones first.</para>
462 <para>Test them. You can see exactly what changes you've
463 made by using the <literal>cvs diff</literal> command:</para>
467 <para>lists all the changes (using the
468 <literal>diff</literal> command) in and below the current
469 directory. In emacs, <literal>C-c C-v =</literal> runs
470 <literal>cvs diff</literal> on the current buffer and shows
471 you the results.</para>
475 <para>If you changed something in the
476 <literal>fptools/libraries</literal> subdirectories, also run
477 <literal>make html</literal> to check if the documentation can
478 be generated successfully, too.</para>
482 <para>Before checking in a change, you need to update your
489 <para>This pulls in any changes that other people have made,
490 and merges them with yours. If there are any conflicts, CVS
491 will tell you, and you'll have to resolve them before you
492 can check your changes in. The documentation describes what
493 to do in the event of a conflict.</para>
495 <para>It's not always necessary to do a full cvs update
496 before checking in a change, since CVS will always tell you
497 if you try to check in a file that someone else has changed.
498 However, you should still update at regular intervals to
499 avoid making changes that don't work in conjuction with
500 changes that someone else made. Keeping an eye on what goes
501 by on the mailing list can help here.</para>
505 <para>When you're happy that your change isn't going to
506 break anything, check it in. For a one-file change:</para>
509 $ cvs commit <replaceable>filename</replaceable>
512 <para>CVS will then pop up an editor for you to enter a
513 "commit message", this is just a short description
514 of what your change does, and will be kept in the history of
517 <para>If you're using emacs, simply load up the file into a
518 buffer and type <literal>C-x C-q</literal>, and emacs will
519 prompt for a commit message and then check in the file for
522 <para>For a multiple-file change, things are a bit
523 trickier. There are several ways to do this, but this is the
524 way I find easiest. First type the commit message into a
525 temporary file. Then either</para>
528 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
531 <para>or, if nothing else has changed in this part of the
535 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
538 <para>where <replaceable>directory</replaceable> is a common
539 parent directory for all your changes, and
540 <replaceable>commit-message</replaceable> is the name of the
541 file containing the commit message.</para>
543 <para>Shortly afterwards, you'll get some mail from the
544 relevant mailing list saying which files changed, and giving
545 the commit message. For a multiple-file change, you should
546 still get only <emphasis>one</emphasis> message.</para>
551 <sect2 id="cvs-update">
552 <title>Updating Your Source Tree</title>
554 <para>It can be tempting to cvs update just part of a source
555 tree to bring in some changes that someone else has made, or
556 before committing your own changes. This is NOT RECOMMENDED!
557 Quite often changes in one part of the tree are dependent on
558 changes in another part of the tree (the
559 <literal>mk/*.mk</literal> files are a good example where
560 problems crop up quite often). Having an inconsistent tree is a
561 major cause of headaches. </para>
563 <para>So, to avoid a lot of hassle, follow this recipe for
564 updating your tree:</para>
568 $ cvs update -P 2>&1 | tee log</screen>
570 <para>Look at the log file, and fix any conflicts (denoted by a
571 <quote>C</quote> in the first column). New directories may have
572 appeared in the repository; CVS doesn't check these out by
573 default, so to get new directories you have to explicitly do
575 $ cvs update -d</screen>
576 in each project subdirectory. Don't do this at the top level,
577 because then <emphasis>all</emphasis> the projects will be
580 <para>If you're using multiple build trees, then for every build
581 tree you have pointing at this source tree, you need to update
582 the links in case any new files have appeared: </para>
585 $ cd <replaceable>build-tree</replaceable>
586 $ lndir <replaceable>source-tree</replaceable>
589 <para>Some files might have been removed, so you need to remove
590 the links pointing to these non-existent files:</para>
593 $ find . -xtype l -exec rm '{}' \;
596 <para>To be <emphasis>really</emphasis> safe, you should do
599 <screen>$ gmake all</screen>
601 <para>from the top-level, to update the dependencies and build
602 any changed files. </para>
605 <sect2 id="cvs-tags">
606 <title>GHC Tag Policy</title>
608 <para>If you want to check out a particular version of GHC,
609 you'll need to know how we tag versions in the repository. The
610 policy (as of 4.04) is:</para>
614 <para>The tree is branched before every major release. The
615 branch tag is <literal>ghc-x-xx-branch</literal>, where
616 <literal>x-xx</literal> is the version number of the release
617 with the <literal>'.'</literal> replaced by a
618 <literal>'-'</literal>. For example, the 4.04 release lives
619 on <literal>ghc-4-04-branch</literal>.</para>
623 <para>The release itself is tagged with
624 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
625 called <literal>ghc-4-06</literal>.</para>
629 <para>We didn't always follow these guidelines, so to see
630 what tags there are for previous versions, do <literal>cvs
631 log</literal> on a file that's been around for a while (like
632 <literal>fptools/ghc/README</literal>).</para>
636 <para>So, to check out a fresh GHC 4.06 tree you would
640 $ cvs co -r ghc-4-06 fpconfig
642 $ cvs co -r ghc-4-06 ghc hslibs
646 <sect2 id="cvs-hints">
647 <title>General Hints</title>
651 <para>As a general rule: commit changes in small units,
652 preferably addressing one issue or implementing a single
653 feature. Provide a descriptive log message so that the
654 repository records exactly which changes were required to
655 implement a given feature/fix a bug. I've found this
656 <emphasis>very</emphasis> useful in the past for finding out
657 when a particular bug was introduced: you can just wind back
658 the CVS tree until the bug disappears.</para>
662 <para>Keep the sources at least *buildable* at any given
663 time. No doubt bugs will creep in, but it's quite easy to
664 ensure that any change made at least leaves the tree in a
665 buildable state. We do nightly builds of GHC to keep an eye
666 on what things work/don't work each day and how we're doing
667 in relation to previous verions. This idea is truely wrecked
668 if the compiler won't build in the first place!</para>
672 <para>To check out extra bits into an already-checked-out
673 tree, use the following procedure. Suppose you have a
674 checked-out fptools tree containing just ghc, and you want
675 to add nofib to it:</para>
686 $ cvs update -d nofib
689 <para>(the -d flag tells update to create a new
690 directory). If you just want part of the nofib suite, you
695 $ cvs checkout nofib/spectral
698 <para>This works because <literal>nofib</literal> is a
699 module in its own right, and spectral is a subdirectory of
700 the nofib module. The path argument to checkout must always
701 start with a module name. There's no equivalent form of this
702 command using <literal>update</literal>.</para>
708 <sect1 id="projects">
709 <title>What projects are there?</title>
711 <para>The <literal>fptools</literal> suite consists of several
712 <firstterm>projects</firstterm>, most of which can be downloaded,
713 built and installed individually. Each project corresponds to a
714 subdirectory in the source tree, and if checking out from CVS then
715 each project can be checked out individually by sitting in the top
716 level of your source tree and typing <command>cvs checkout
717 <replaceable>project</replaceable></command>.</para>
719 <para>Here is a list of the projects currently available:</para>
723 <term><literal>alex</literal></term>
724 <indexterm><primary><literal>alex</literal></primary>
725 <secondary>project</secondary></indexterm>
728 url="http://www.haskell.org/alex/">Alex</ulink> lexical
729 analyser generator for Haskell.</para>
734 <term><literal>ghc</literal></term>
735 <indexterm><primary><literal>ghc</literal></primary>
736 <secondary>project</secondary></indexterm>
738 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
739 Haskell Compiler</ulink> (minus libraries). Absolutely
740 required for building GHC.</para>
745 <term><literal>glafp-utils</literal></term>
746 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
748 <para>Utility programs, some of which are used by the
749 build/installation system. Required for pretty much
755 <term><literal>greencard</literal></term>
756 <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
759 url="http://www.haskell.org/greencard/">GreenCard</ulink>
760 system for generating Haskell foreign function
766 <term><literal>haggis</literal></term>
767 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
770 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
771 Haskell GUI framework.</para>
776 <term><literal>haddock</literal></term>
777 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
780 url="http://www.haskell.org/haddock/">Haddock</ulink>
781 documentation tool.</para>
786 <term><literal>happy</literal></term>
787 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
790 url="http://www.haskell.org/happy/">Happy</ulink> Parser
796 <term><literal>hdirect</literal></term>
797 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
800 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
801 Haskell interoperability tool.</para>
806 <term><literal>hood</literal></term>
807 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
809 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
810 Object Observation Debugger</ulink>.</para>
815 <term><literal>hslibs</literal></term>
816 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
818 <para>Supplemental libraries for GHC
819 (<emphasis>required</emphasis> for building GHC).</para>
824 <term><literal>libraries</literal></term>
825 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
827 <para>Hierarchical Haskell library suite
828 (<emphasis>required</emphasis> for building GHC).</para>
833 <term><literal>mhms</literal></term>
834 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
836 <para>The Modular Haskell Metric System.</para>
841 <term><literal>nofib</literal></term>
842 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
844 <para>The NoFib suite: A collection of Haskell programs used
845 primarily for benchmarking.</para>
850 <term><literal>testsuite</literal></term>
851 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
853 <para>A testing framework, including GHC's regression test
859 <para>So, to build GHC you need at least the
860 <literal>ghc</literal>, <literal>libraries</literal> and
861 <literal>hslibs</literal> projects (a GHC source distribution will
862 already include the bits you need).</para>
865 <sect1 id="sec-build-checks">
866 <title>Things to check before you start</title>
868 <para>Here's a list of things to check before you get
874 <indexterm><primary>Disk space needed</primary></indexterm>
875 <para>Disk space needed: from about 100Mb for a basic GHC
876 build, up to probably 500Mb for a GHC build with everything
877 included (libraries built several different ways,
882 <para>Use an appropriate machine / operating system. <xref
883 linkend="sec-port-info"> lists the supported platforms; if
884 yours isn't amongst these then you can try porting GHC (see
885 <xref linkend="sec-porting-ghc">).</para>
889 <para>Be sure that the “pre-supposed” utilities are
890 installed. <Xref LinkEnd="sec-pre-supposed">
895 <para>If you have any problem when building or installing the
896 Glasgow tools, please check the “known pitfalls” (<Xref
897 LinkEnd="sec-build-pitfalls">). Also check the FAQ for the
898 version you're building, which is part of the User's Guide and
899 available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
902 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
904 <para>If you feel there is still some shortcoming in our
905 procedure or instructions, please report it.</para>
907 <para>For GHC, please see the <ulink
908 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
909 section of the GHC Users' Guide</ulink>, to maximise the
910 usefulness of your report.</para>
912 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
913 <para>If in doubt, please send a message to
914 <email>glasgow-haskell-bugs@haskell.org</email>.
915 <indexterm><primary>bugs</primary><secondary>mailing
916 list</secondary></indexterm></para>
921 <sect1 id="sec-port-info">
922 <title>What machines the Glasgow tools run on</title>
924 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
925 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
926 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
928 <para>The main question is whether or not the Haskell compiler
929 (GHC) runs on your platform.</para>
931 <para>A “platform” is a
932 architecture/manufacturer/operating-system combination, such as
933 <literal>sparc-sun-solaris2</literal>. Other common ones are
934 <literal>alpha-dec-osf2</literal>,
935 <literal>hppa1.1-hp-hpux9</literal>,
936 <literal>i386-unknown-linux</literal>,
937 <literal>i386-unknown-solaris2</literal>,
938 <literal>i386-unknown-freebsd</literal>,
939 <literal>i386-unknown-cygwin32</literal>,
940 <literal>m68k-sun-sunos4</literal>,
941 <literal>mips-sgi-irix5</literal>,
942 <literal>sparc-sun-sunos4</literal>,
943 <literal>sparc-sun-solaris2</literal>,
944 <literal>powerpc-ibm-aix</literal>.</para>
946 <para>Some libraries may only work on a limited number of
947 platforms; for example, a sockets library is of no use unless the
948 operating system supports the underlying BSDisms.</para>
951 <title>What platforms the Haskell compiler (GHC) runs on</title>
953 <indexterm><primary>fully-supported platforms</primary></indexterm>
954 <indexterm><primary>native-code generator</primary></indexterm>
955 <indexterm><primary>registerised ports</primary></indexterm>
956 <indexterm><primary>unregisterised ports</primary></indexterm>
958 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
959 native-code generator; (b) next best is a
960 “registerised” port; (c) the bare minimum is an
961 “unregisterised” port.
962 (“Unregisterised” is so terrible that we won't say
963 more about it).</para>
965 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
966 FreeBSD and Linux, so those are the best supported platforms,
967 unsurprisingly.</para>
969 <para>Here's everything that's known about GHC ports. We
970 identify platforms by their “canonical”
971 CPU/Manufacturer/OS triple.</para>
975 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
976 <indexterm><primary>alpha-dec-osf</primary></indexterm>
977 <indexterm><primary>alpha-dec-linux</primary></indexterm>
978 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
979 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
980 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
983 <para>The OSF port is currently working (as of GHC version
984 5.02.1) and well supported. The native code generator is
985 currently non-working. Other operating systems will
986 require some minor porting.</para>
991 <term>sparc-sun-sunos4</term>
992 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
994 <para>Probably works with minor tweaks, hasn't been tested
1000 <term>sparc-sun-solaris2</term>
1001 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
1003 <para>Fully supported (at least for Solaris 2.7 and 2.6),
1004 including native-code generator.</para>
1009 <term>sparc-unknown-openbsd</term>
1010 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
1012 <para>Supported, including native-code generator. The
1013 same should also be true of NetBSD</para>
1018 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
1019 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1021 <para>A registerised port is available for version 4.08,
1022 but GHC hasn't been built on that platform since (as far
1023 as we know). No native-code generator.</para>
1028 <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
1029 <indexterm><primary>i386-*-linux</primary></indexterm>
1031 <para>GHC works registerised and has a native code
1032 generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
1033 or later. NOTE about <literal>glibc</literal> versions:
1034 GHC binaries built on a system running <literal>glibc
1035 2.0</literal> won't work on a system running
1036 <literal>glibc 2.1</literal>, and vice versa. In general,
1037 don't expect compatibility between
1038 <literal>glibc</literal> versions, even if the shared
1039 library version hasn't changed.</para>
1044 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
1046 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1048 <para>GHC works registerised. Pre-built packages are
1049 available in the native package format, so if you just
1050 need binaries you're better off just installing the
1051 package (it might even be on your installation
1057 <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
1058 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1060 <para>Supported, with native code generator. Packages are
1061 available through the ports system in the native package
1067 <term>i386-unknown-netbsd (PCs running NetBSD and
1069 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1071 <para>Will require some minor porting effort, but should
1072 work registerised.</para>
1077 <term>i386-unknown-mingw32 (PCs running Windows)</term>
1078 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1080 <para>Fully supported under Win9x, WinNT, Win2k, and
1081 WinXP. Includes a native code generator. Building from
1082 source requires a recent <ulink
1083 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1084 to be installed.</para>
1089 <term>ia64-unknown-linux</term>
1090 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1092 <para>Supported, except there is no native code
1098 <term>x86_64-unknown-linux</term>
1099 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1101 <para>GHC currently works unregisterised. A registerised
1102 port is in progress.</para>
1107 <term>mips-sgi-irix5</term>
1108 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1110 <para>Port has worked in the past, but hasn't been tested
1111 for some time (and will certainly have rotted in various
1112 ways). As usual, we don't have access to machines and
1113 there hasn't been an overwhelming demand for this port,
1114 but feel free to get in touch.</para>
1119 <term>mips64-sgi-irix6</term>
1120 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
1122 <para>GHC currently works unregisterised.</para>
1127 <term>powerpc-ibm-aix</term>
1128 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1130 <para>Port currently doesn't work, needs some minimal
1131 porting effort. As usual, we don't have access to
1132 machines and there hasn't been an overwhelming demand for
1133 this port, but feel free to get in touch.</para>
1138 <term>powerpc-apple-darwin</term>
1139 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1141 <para>Supported registerised. Native code generator is
1142 almost working.</para>
1147 <term>powerpc-apple-linux</term>
1148 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1150 <para>Not supported (yet).</para>
1155 <para>Various other systems have had GHC ported to them in the
1156 distant past, including various Motorola 68k boxes. The 68k
1157 support still remains, but porting to one of these systems will
1158 certainly be a non-trivial task.</para>
1162 <title>What machines the other tools run on</title>
1164 <para>Unless you hear otherwise, the other tools work if GHC
1170 <sect1 id="sec-pre-supposed">
1171 <title>Installing pre-supposed utilities</title>
1173 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1174 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1176 <para>Here are the gory details about some utility programs you
1177 may need; <command>perl</command>, <command>gcc</command> and
1178 <command>happy</command> are the only important
1179 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1180 important if you're going for Parallel Haskell.) The
1181 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1182 script will tell you if you are missing something.</para>
1188 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1189 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1191 <para>GHC is required to build many of the tools, including
1192 GHC itself. If you need to port GHC to your platform
1193 because there isn't a binary distribution of GHC available,
1194 then see <xref linkend="sec-porting-ghc">.</para>
1196 <para>Which version of GHC you need will depend on the
1197 packages you intend to build. GHC itself will normally
1198 build using one of several older versions of itself - check
1199 the announcement or release notes for details.</para>
1205 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1206 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1208 <para><emphasis>You have to have Perl to proceed!</emphasis>
1209 Perl version 5 at least is required. GHC has been known to
1210 tickle bugs in Perl, so if you find that Perl crashes when
1211 running GHC try updating (or downgrading) your Perl
1212 installation. Versions of Perl that we use and are known to
1213 be fairly stable are 5.005 and 5.6.1.</para>
1215 <para>For Win32 platforms, you should use the binary
1216 supplied in the InstallShield (copy it to
1217 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1220 <para>Perl should be put somewhere so that it can be invoked
1221 by the <literal>#!</literal> script-invoking
1222 mechanism. The full pathname may need to be less than 32
1223 characters long on some systems.</para>
1228 <term>GNU C (<command>gcc</command>)</term>
1229 <indexterm><primary>pre-supposed: GCC (GNU C
1230 compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
1231 compiler), pre-supposed</primary></indexterm>
1233 <para>We recommend using GCC version 2.95.2 on all
1234 platforms. Failing that, version 2.7.2 is stable on most
1235 platforms. Earlier versions of GCC can be assumed not to
1236 work, and versions in between 2.7.2 and 2.95.2 (including
1237 <command>egcs</command>) have varying degrees of stability
1238 depending on the platform.</para>
1240 <para>GCC 3.2 is currently known to have problems building
1241 GHC on Sparc, but is stable on x86.</para>
1243 <para>If your GCC dies with “internal error” on
1244 some GHC source file, please let us know, so we can report
1245 it and get things improved. (Exception: on x86
1246 boxes—you may need to fiddle with GHC's
1247 <option>-monly-N-regs</option> option; see the User's
1253 <term>GNU Make</term>
1254 <indexterm><primary>make</primary><secondary>GNU</secondary>
1257 <para>The fptools build system makes heavy use of features
1258 specific to GNU <command>make</command>, so you must have
1259 this installed in order to build any of the fptools
1266 <indexterm><primary>Happy</primary></indexterm>
1268 <para>Happy is a parser generator tool for Haskell, and is
1269 used to generate GHC's parsers. Happy is written in
1270 Haskell, and is a project in the CVS repository
1271 (<literal>fptools/happy</literal>). It can be built from
1272 source, but bear in mind that you'll need GHC installed in
1273 order to build it. To avoid the chicken/egg problem,
1274 install a binary distribution of either Happy or GHC to get
1275 started. Happy distributions are available from <ulink
1276 url="http://www.haskell.org/happy/">Happy's Web
1277 Page</ulink>.</para>
1283 <indexterm><primary>Alex</primary></indexterm>
1285 <para>Alex is a lexical-analyser generator for Haskell,
1286 which GHC uses to generate its lexer. Like Happy, Alex is
1287 written in Haskell and is a project in the CVS repository.
1288 Alex distributions are available from <ulink
1289 url="http://www.haskell.org/alex/">Alex's Web
1290 Page</ulink>.</para>
1295 <term>Autoconf</term>
1296 <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
1297 <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
1299 <para>GNU Autoconf is needed if you intend to build from the
1300 CVS sources, it is <emphasis>not</emphasis> needed if you
1301 just intend to build a standard source distribution.</para>
1303 <para>Version 2.52 or later of autoconf is required.
1304 NB. vesrion 2.13 will no longer work, as of GHC version
1307 <para>Autoconf builds the <command>configure</command>
1308 script from <filename>configure.ac</filename> and
1309 <filename>aclocal.m4</filename>. If you modify either of
1310 these files, you'll need <command>autoconf</command> to
1311 rebuild <filename>configure</filename>.</para>
1316 <term><command>sed</command></term>
1317 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1318 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1320 <para>You need a working <command>sed</command> if you are
1321 going to build from sources. The build-configuration stuff
1322 needs it. GNU sed version 2.0.4 is no good! It has a bug
1323 in it that is tickled by the build-configuration. 2.0.5 is
1324 OK. Others are probably OK too (assuming we don't create too
1325 elaborate configure scripts.)</para>
1330 <para>One <literal>fptools</literal> project is worth a quick note
1331 at this point, because it is useful for all the others:
1332 <literal>glafp-utils</literal> contains several utilities which
1333 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1334 Like <command>lndir</command> for creating symbolic link
1337 <sect2 id="pre-supposed-gph-tools">
1338 <title>Tools for building parallel GHC (GPH)</title>
1342 <term>PVM version 3:</term>
1343 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1344 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1346 <para>PVM is the Parallel Virtual Machine on which
1347 Parallel Haskell programs run. (You only need this if you
1348 plan to run Parallel Haskell. Concurrent Haskell, which
1349 runs concurrent threads on a uniprocessor doesn't need
1350 it.) Underneath PVM, you can have (for example) a network
1351 of workstations (slow) or a multiprocessor box
1354 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1355 It is readily available on the net; I think I got it from
1356 <literal>research.att.com</literal>, in
1357 <filename>netlib</filename>.</para>
1359 <para>A PVM installation is slightly quirky, but easy to
1360 do. Just follow the <filename>Readme</filename>
1361 instructions.</para>
1366 <term><command>bash</command>:</term>
1367 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1369 <para>Sadly, the <command>gr2ps</command> script, used to
1370 convert “parallelism profiles” to PostScript,
1371 is written in Bash (GNU's Bourne Again shell). This bug
1372 will be fixed (someday).</para>
1378 <sect2 id="pre-supposed-other-tools">
1379 <title>Other useful tools</title>
1384 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1385 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1387 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1388 to build a couple of utilities in
1389 <literal>glafp-utils</literal>. Depending on your
1390 operating system, the supplied <command>lex</command> may
1391 or may not work; you should get the GNU version.</para>
1396 <para>More tools are required if you want to format the documentation
1397 that comes with GHC and other fptools projects. See <xref
1398 linkend="building-docs">.</para>
1402 <sect1 id="sec-building-from-source">
1403 <title>Building from source</title>
1405 <indexterm><primary>Building from source</primary></indexterm>
1406 <indexterm><primary>Source, building from</primary></indexterm>
1408 <para>You've been rash enough to want to build some of the Glasgow
1409 Functional Programming tools (GHC, Happy, nofib, etc.) from
1410 source. You've slurped the source, from the CVS repository or
1411 from a source distribution, and now you're sitting looking at a
1412 huge mound of bits, wondering what to do next.</para>
1414 <para>Gingerly, you type <command>make</command>. Wrong
1417 <para>This rest of this guide is intended for duffers like me, who
1418 aren't really interested in Makefiles and systems configurations,
1419 but who need a mental model of the interlocking pieces so that
1420 they can make them work, extend them consistently when adding new
1421 software, and lay hands on them gently when they don't
1424 <sect2 id="quick-start">
1425 <title>Quick Start</title>
1427 <para>If you are starting from a source distribution, and just
1428 want a completely standard build, then the following should
1431 <screen>$ ./configure
1436 <para>For GHC, this will do a 2-stage bootstrap build of the
1437 compiler, with profiling libraries, and install the
1440 <para>If you want to do anything at all non-standard, or you
1441 want to do some development, read on...</para>
1444 <sect2 id="sec-source-tree">
1445 <title>Your source tree</title>
1447 <para>The source code is held in your <emphasis>source
1448 tree</emphasis>. The root directory of your source tree
1449 <emphasis>must</emphasis> contain the following directories and
1454 <para><filename>Makefile</filename>: the root
1459 <para><filename>mk/</filename>: the directory that contains
1460 the main Makefile code, shared by all the
1461 <literal>fptools</literal> software.</para>
1465 <para><filename>configure.ac</filename>,
1466 <filename>config.sub</filename>,
1467 <filename>config.guess</filename>: these files support the
1468 configuration process.</para>
1472 <para><filename>install-sh</filename>.</para>
1476 <para>All the other directories are individual
1477 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1478 system—for example, the Glasgow Haskell Compiler
1479 (<literal>ghc</literal>), the Happy parser generator
1480 (<literal>happy</literal>), the <literal>nofib</literal>
1481 benchmark suite, and so on. You can have zero or more of these.
1482 Needless to say, some of them are needed to build others.</para>
1484 <para>The important thing to remember is that even if you want
1485 only one project (<literal>happy</literal>, say), you must have
1486 a source tree whose root directory contains
1487 <filename>Makefile</filename>, <filename>mk/</filename>,
1488 <filename>configure.ac</filename>, and the project(s) you want
1489 (<filename>happy/</filename> in this case). You cannot get by
1490 with just the <filename>happy/</filename> directory.</para>
1494 <title>Build trees</title>
1495 <indexterm><primary>build trees</primary></indexterm>
1496 <indexterm><primary>link trees, for building</primary></indexterm>
1498 <para>If you just want to build the software once on a single
1499 platform, then your source tree can also be your build tree, and
1500 you can skip the rest of this section.</para>
1502 <para>We often want to build multiple versions of our software
1503 for different architectures, or with different options
1504 (e.g. profiling). It's very desirable to share a single copy of
1505 the source code among all these builds.</para>
1507 <para>So for every source tree we have zero or more
1508 <emphasis>build trees</emphasis>. Each build tree is initially
1509 an exact copy of the source tree, except that each file is a
1510 symbolic link to the source file, rather than being a copy of
1511 the source file. There are “standard” Unix
1512 utilities that make such copies, so standard that they go by
1514 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1515 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1516 are two (If you don't have either, the source distribution
1517 includes sources for the X11
1518 <command>lndir</command>—check out
1519 <filename>fptools/glafp-utils/lndir</filename>). See <Xref
1520 LinkEnd="sec-storysofar"> for a typical invocation.</para>
1522 <para>The build tree does not need to be anywhere near the
1523 source tree in the file system. Indeed, one advantage of
1524 separating the build tree from the source is that the build tree
1525 can be placed in a non-backed-up partition, saving your systems
1526 support people from backing up untold megabytes of
1527 easily-regenerated, and rapidly-changing, gubbins. The golden
1528 rule is that (with a single exception—<XRef
1529 LinkEnd="sec-build-config">) <emphasis>absolutely everything in
1530 the build tree is either a symbolic link to the source tree, or
1531 else is mechanically generated</emphasis>. It should be
1532 perfectly OK for your build tree to vanish overnight; an hour or
1533 two compiling and you're on the road again.</para>
1535 <para>You need to be a bit careful, though, that any new files
1536 you create (if you do any development work) are in the source
1537 tree, not a build tree!</para>
1539 <para>Remember, that the source files in the build tree are
1540 <emphasis>symbolic links</emphasis> to the files in the source
1541 tree. (The build tree soon accumulates lots of built files like
1542 <filename>Foo.o</filename>, as well.) You can
1543 <emphasis>delete</emphasis> a source file from the build tree
1544 without affecting the source tree (though it's an odd thing to
1545 do). On the other hand, if you <emphasis>edit</emphasis> a
1546 source file from the build tree, you'll edit the source-tree
1547 file directly. (You can set up Emacs so that if you edit a
1548 source file from the build tree, Emacs will silently create an
1549 edited copy of the source file in the build tree, leaving the
1550 source file unchanged; but the danger is that you think you've
1551 edited the source file whereas actually all you've done is edit
1552 the build-tree copy. More commonly you do want to edit the
1553 source file.)</para>
1555 <para>Like the source tree, the top level of your build tree
1556 must be (a linked copy of) the root directory of the
1557 <literal>fptools</literal> suite. Inside Makefiles, the root of
1558 your build tree is called
1559 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1560 In the rest of this document path names are relative to
1561 <constant>$(FPTOOLS_TOP)</constant> unless
1562 otherwise stated. For example, the file
1563 <filename>ghc/mk/target.mk</filename> is actually
1564 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
1567 <sect2 id="sec-build-config">
1568 <title>Getting the build you want</title>
1570 <para>When you build <literal>fptools</literal> you will be
1571 compiling code on a particular <emphasis>host
1572 platform</emphasis>, to run on a particular <emphasis>target
1573 platform</emphasis> (usually the same as the host
1574 platform)<indexterm><primary>platform</primary></indexterm>.
1575 The difficulty is that there are minor differences between
1576 different platforms; minor, but enough that the code needs to be
1577 a bit different for each. There are some big differences too:
1578 for a different architecture we need to build GHC with a
1579 different native-code generator.</para>
1581 <para>There are also knobs you can turn to control how the
1582 <literal>fptools</literal> software is built. For example, you
1583 might want to build GHC optimised (so that it runs fast) or
1584 unoptimised (so that you can compile it fast after you've
1585 modified it. Or, you might want to compile it with debugging on
1586 (so that extra consistency-checking code gets included) or off.
1589 <para>All of this stuff is called the
1590 <emphasis>configuration</emphasis> of your build. You set the
1591 configuration using a three-step process.</para>
1595 <term>Step 1: get ready for configuration.</term>
1597 <para>NOTE: if you're starting from a source distribution,
1598 rather than CVS sources, you can skip this step.</para>
1600 <para>Change directory to
1601 <constant>$(FPTOOLS_TOP)</constant> and
1603 <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
1604 (with no arguments). This GNU program converts
1605 <filename><constant>$(FPTOOLS_TOP)</constant>/configure.ac</filename>
1606 to a shell script called
1607 <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
1610 <para>Some projects, including GHC, have their own
1611 configure script. If there's an
1612 <constant>$(FPTOOLS_TOP)/<project>/configure.ac</constant>,
1613 then you need to run <command>autoconf</command> in that
1614 directory too.</para>
1616 <para>Both these steps are completely
1617 platform-independent; they just mean that the
1618 human-written file (<filename>configure.ac</filename>) can
1619 be short, although the resulting shell script,
1620 <command>configure</command>, and
1621 <filename>mk/config.h.in</filename>, are long.</para>
1626 <term>Step 2: system configuration.</term>
1628 <para>Runs the newly-created <command>configure</command>
1629 script, thus:</para>
1632 ./configure <optional><parameter>args</parameter></optional>
1635 <para><command>configure</command>'s mission is to scurry
1636 round your computer working out what architecture it has,
1637 what operating system, whether it has the
1638 <Function>vfork</Function> system call, where
1639 <command>tar</command> is kept, whether
1640 <command>gcc</command> is available, where various obscure
1641 <literal>#include</literal> files are, whether it's a
1642 leap year, and what the systems manager had for lunch. It
1643 communicates these snippets of information in two
1650 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1652 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1653 substituting for things between
1654 “<literal>@</literal>” brackets. So,
1655 “<literal>@HaveGcc@</literal>” will be
1656 replaced by “<literal>YES</literal>” or
1657 “<literal>NO</literal>” depending on what
1658 <command>configure</command> finds.
1659 <filename>mk/config.mk</filename> is included by every
1660 Makefile (directly or indirectly), so the
1661 configuration information is thereby communicated to
1662 all Makefiles.</para>
1666 <para> It translates
1667 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1669 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1670 The latter is <literal>#include</literal>d by
1671 various C programs, which can thereby make use of
1672 configuration information.</para>
1676 <para><command>configure</command> takes some optional
1677 arguments. Use <literal>./configure --help</literal> to
1678 get a list of the available arguments. Here are some of
1679 the ones you might need:</para>
1683 <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
1684 <indexterm><primary><literal>--with-ghc</literal></primary>
1687 <para>Specifies the path to an installed GHC which
1688 you would like to use. This compiler will be used
1689 for compiling GHC-specific code (eg. GHC itself).
1690 This option <emphasis>cannot</emphasis> be specified
1691 using <filename>build.mk</filename> (see later),
1692 because <command>configure</command> needs to
1693 auto-detect the version of GHC you're using. The
1694 default is to look for a compiler named
1695 <literal>ghc</literal> in your path.</para>
1700 <term><literal>--with-hc=<parameter>path</parameter></literal></term>
1701 <indexterm><primary><literal>--with-hc</literal></primary>
1704 <para>Specifies the path to any installed Haskell
1705 compiler. This compiler will be used for compiling
1706 generic Haskell code. The default is to use
1707 <literal>ghc</literal>.</para>
1712 <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
1713 <indexterm><primary><literal>--with-gcc</literal></primary>
1716 <para>Specifies the path to the installed GCC. This
1717 compiler will be used to compile all C files,
1718 <emphasis>except</emphasis> any generated by the
1719 installed Haskell compiler, which will have its own
1720 idea of which C compiler (if any) to use. The
1721 default is to use <literal>gcc</literal>.</para>
1726 <para><command>configure</command> caches the results of
1727 its run in <filename>config.cache</filename>. Quite often
1728 you don't want that; you're running
1729 <command>configure</command> a second time because
1730 something has changed. In that case, simply delete
1731 <filename>config.cache</filename>.</para>
1736 <term>Step 3: build configuration.</term>
1738 <para>Next, you say how this build of
1739 <literal>fptools</literal> is to differ from the standard
1740 defaults by creating a new file
1741 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1742 <emphasis>in the build tree</emphasis>. This file is the
1743 one and only file you edit in the build tree, precisely
1744 because it says how this build differs from the source.
1745 (Just in case your build tree does die, you might want to
1746 keep a private directory of <filename>build.mk</filename>
1747 files, and use a symbolic link in each build tree to point
1748 to the appropriate one.) So
1749 <filename>mk/build.mk</filename> never exists in the
1750 source tree—you create one in each build tree from
1751 the template. We'll discuss what to put in it
1757 <para>And that's it for configuration. Simple, eh?</para>
1759 <para>What do you put in your build-specific configuration file
1760 <filename>mk/build.mk</filename>? <emphasis>For almost all
1761 purposes all you will do is put make variable definitions that
1762 override those in</emphasis>
1763 <filename>mk/config.mk.in</filename>. The whole point of
1764 <filename>mk/config.mk.in</filename>—and its derived
1765 counterpart <filename>mk/config.mk</filename>—is to define
1766 the build configuration. It is heavily commented, as you will
1767 see if you look at it. So generally, what you do is look at
1768 <filename>mk/config.mk.in</filename>, and add definitions in
1769 <filename>mk/build.mk</filename> that override any of the
1770 <filename>config.mk</filename> definitions that you want to
1771 change. (The override occurs because the main boilerplate file,
1772 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1773 includes <filename>build.mk</filename> after
1774 <filename>config.mk</filename>.)</para>
1776 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1777 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1779 <para>For example, <filename>config.mk.in</filename> contains
1780 the definition:</para>
1783 GhcHcOpts=-O -Rghc-timing
1786 <para>The accompanying comment explains that this is the list of
1787 flags passed to GHC when building GHC itself. For doing
1788 development, it is wise to add <literal>-DDEBUG</literal>, to
1789 enable debugging code. So you would add the following to
1790 <filename>build.mk</filename>:</para>
1792 <para>or, if you prefer,</para>
1795 GhcHcOpts += -DDEBUG
1798 <para>GNU <command>make</command> allows existing definitions to
1799 have new text appended using the “<literal>+=</literal>”
1800 operator, which is quite a convenient feature.)</para>
1802 <para>If you want to remove the <literal>-O</literal> as well (a
1803 good idea when developing, because the turn-around cycle gets a
1804 lot quicker), you can just override
1805 <literal>GhcLibHcOpts</literal> altogether:</para>
1808 GhcHcOpts=-DDEBUG -Rghc-timing
1811 <para>When reading <filename>config.mk.in</filename>, remember
1812 that anything between “@...@” signs is going to be substituted
1813 by <command>configure</command> later. You
1814 <emphasis>can</emphasis> override the resulting definition if
1815 you want, but you need to be a bit surer what you are doing.
1816 For example, there's a line that says:</para>
1822 <para>This defines the Make variables <constant>TAR</constant>
1823 to the pathname for a <command>tar</command> that
1824 <command>configure</command> finds somewhere. If you have your
1825 own pet <command>tar</command> you want to use instead, that's
1826 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1832 <para>You do not <emphasis>have</emphasis> to have a
1833 <filename>mk/build.mk</filename> file at all; if you don't,
1834 you'll get all the default settings from
1835 <filename>mk/config.mk.in</filename>.</para>
1837 <para>You can also use <filename>build.mk</filename> to override
1838 anything that <command>configure</command> got wrong. One place
1839 where this happens often is with the definition of
1840 <constant>FPTOOLS_TOP_ABS</constant>: this
1841 variable is supposed to be the canonical path to the top of your
1842 source tree, but if your system uses an automounter then the
1843 correct directory is hard to find automatically. If you find
1844 that <command>configure</command> has got it wrong, just put the
1845 correct definition in <filename>build.mk</filename>.</para>
1849 <sect2 id="sec-storysofar">
1850 <title>The story so far</title>
1852 <para>Let's summarise the steps you need to carry to get
1853 yourself a fully-configured build tree from scratch.</para>
1857 <para> Get your source tree from somewhere (CVS repository
1858 or source distribution). Say you call the root directory
1859 <filename>myfptools</filename> (it does not have to be
1860 called <filename>fptools</filename>). Make sure that you
1861 have the essential files (see <XRef
1862 LinkEnd="sec-source-tree">).</para>
1867 <para>(Optional) Use <command>lndir</command> or
1868 <command>mkshadowdir</command> to create a build tree.</para>
1872 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1875 <para>(N.B. <command>mkshadowdir</command>'s first argument
1876 is taken relative to its second.) You probably want to give
1877 the build tree a name that suggests its main defining
1878 characteristic (in your mind at least), in case you later
1883 <para>Change directory to the build tree. Everything is
1884 going to happen there now.</para>
1887 $ cd /scratch/joe-bloggs/myfptools-sun4
1893 <para>Prepare for system configuration:</para>
1899 <para>(You can skip this step if you are starting from a
1900 source distribution, and you already have
1901 <filename>configure</filename> and
1902 <filename>mk/config.h.in</filename>.)</para>
1904 <para>Some projects, including GHC itself, have their own
1905 configure scripts, so it is necessary to run autoconf again
1906 in the appropriate subdirectories. eg:</para>
1909 $ (cd ghc; autoconf)
1914 <para>Do system configuration:</para>
1920 <para>Don't forget to check whether you need to add any
1921 arguments to <literal>configure</literal>; for example, a
1922 common requirement is to specify which GHC to use with
1923 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1927 <para>Create the file <filename>mk/build.mk</filename>,
1928 adding definitions for your desired configuration
1937 <para>You can make subsequent changes to
1938 <filename>mk/build.mk</filename> as often as you like. You do
1939 not have to run any further configuration programs to make these
1940 changes take effect. In theory you should, however, say
1941 <command>gmake clean</command>, <command>gmake all</command>,
1942 because configuration option changes could affect
1943 anything—but in practice you are likely to know what's
1948 <title>Making things</title>
1950 <para>At this point you have made yourself a fully-configured
1951 build tree, so you are ready to start building real
1954 <para>The first thing you need to know is that <emphasis>you
1955 must use GNU <command>make</command>, usually called
1956 <command>gmake</command>, not standard Unix
1957 <command>make</command></emphasis>. If you use standard Unix
1958 <command>make</command> you will get all sorts of error messages
1959 (but no damage) because the <literal>fptools</literal>
1960 <command>Makefiles</command> use GNU <command>make</command>'s
1961 facilities extensively.</para>
1963 <para>To just build the whole thing, <command>cd</command> to
1964 the top of your <literal>fptools</literal> tree and type
1965 <command>gmake</command>. This will prepare the tree and build
1966 the various projects in the correct order.</para>
1969 <sect2 id="sec-bootstrapping">
1970 <title>Bootstrapping GHC</title>
1972 <para>GHC requires a 2-stage bootstrap in order to provide
1973 full functionality, including GHCi. By a 2-stage bootstrap, we
1974 mean that the compiler is built once using the installed GHC,
1975 and then again using the compiler built in the first stage. You
1976 can also build a stage 3 compiler, but this normally isn't
1977 necessary except to verify that the stage 2 compiler is working
1980 <para>Note that when doing a bootstrap, the stage 1 compiler
1981 must be built, followed by the runtime system and libraries, and
1982 then the stage 2 compiler. The correct ordering is implemented
1983 by the top-level fptools <filename>Makefile</filename>, so if
1984 you want everything to work automatically it's best to start
1985 <command>make</command> from the top of the tree. When building
1986 GHC, the top-level fptools <filename>Makefile</filename> is set
1987 up to do a 2-stage bootstrap by default (when you say
1988 <command>make</command>). Some other targets it supports
1995 <para>Build everything as normal, including the stage 1
2003 <para>Build the stage 2 compiler only.</para>
2010 <para>Build the stage 3 compiler only.</para>
2015 <term>bootstrap</term> <term>bootstrap2</term>
2017 <para>Build stage 1 followed by stage 2.</para>
2022 <term>bootstrap3</term>
2024 <para>Build stages 1, 2 and 3.</para>
2029 <term>install</term>
2031 <para>Install everything, including the compiler built in
2032 stage 2. To override the stage, say <literal>make install
2033 stage=<replaceable>n</replaceable></literal> where
2034 <replaceable>n</replaceable> is the stage to install.</para>
2039 <para>The top-level <filename>Makefile</filename> also arranges
2040 to do the appropriate <literal>make boot</literal> steps (see
2041 below) before actually building anything.</para>
2043 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2044 and <literal>stage3</literal> targets also work in the
2045 <literal>ghc/compiler</literal> directory, but don't forget that
2046 each stage requires its own <literal>make boot</literal> step:
2047 for example, you must do</para>
2049 <screen>$ make boot stage=2</screen>
2051 <para>before <literal>make stage2</literal> in
2052 <literal>ghc/compiler</literal>.</para>
2055 <sect2 id="sec-standard-targets">
2056 <title>Standard Targets</title>
2057 <indexterm><primary>targets, standard makefile</primary></indexterm>
2058 <indexterm><primary>makefile targets</primary></indexterm>
2060 <para>In any directory you should be able to make the following:</para>
2064 <term><literal>boot</literal></term>
2066 <para>does the one-off preparation required to get ready
2067 for the real work. Notably, it does <command>gmake
2068 depend</command> in all directories that contain programs.
2069 It also builds the necessary tools for compilation to
2072 <para>Invoking the <literal>boot</literal> target
2073 explicitly is not normally necessary. From the top-level
2074 <literal>fptools</literal> directory, invoking
2075 <literal>gmake</literal> causes <literal>gmake boot
2076 all</literal> to be invoked in each of the project
2077 subdirectories, in the order specified by
2078 <literal>$(AllTargets)</literal> in
2079 <literal>config.mk</literal>.</para>
2081 <para>If you're working in a subdirectory somewhere and
2082 need to update the dependencies, <literal>gmake
2083 boot</literal> is a good way to do it.</para>
2088 <term><literal>all</literal></term>
2090 <para>makes all the final target(s) for this Makefile.
2091 Depending on which directory you are in a “final
2092 target” may be an executable program, a library
2093 archive, a shell script, or a Postscript file. Typing
2094 <command>gmake</command> alone is generally the same as
2095 typing <command>gmake all</command>.</para>
2100 <term><literal>install</literal></term>
2102 <para>installs the things built by <literal>all</literal>
2103 (except for the documentation). Where does it install
2104 them? That is specified by
2105 <filename>mk/config.mk.in</filename>; you can override it
2106 in <filename>mk/build.mk</filename>, or by running
2107 <command>configure</command> with command-line arguments
2108 like <literal>--bindir=/home/simonpj/bin</literal>; see
2109 <literal>./configure --help</literal> for the full
2115 <term><literal>install-docs</literal></term>
2117 <para>installs the documentation. Otherwise behaves just
2118 like <literal>install</literal>.</para>
2123 <term><literal>uninstall</literal></term>
2125 <para>reverses the effect of
2126 <literal>install</literal>.</para>
2131 <term><literal>clean</literal></term>
2133 <para>Delete all files from the current directory that are
2134 normally created by building the program. Don't delete
2135 the files that record the configuration, or files
2136 generated by <command>gmake boot</command>. Also preserve
2137 files that could be made by building, but normally aren't
2138 because the distribution comes with them.</para>
2143 <term><literal>distclean</literal></term>
2145 <para>Delete all files from the current directory that are
2146 created by configuring or building the program. If you
2147 have unpacked the source and built the program without
2148 creating any other files, <literal>make
2149 distclean</literal> should leave only the files that were
2150 in the distribution.</para>
2155 <term><literal>mostlyclean</literal></term>
2157 <para>Like <literal>clean</literal>, but may refrain from
2158 deleting a few files that people normally don't want to
2164 <term><literal>maintainer-clean</literal></term>
2166 <para>Delete everything from the current directory that
2167 can be reconstructed with this Makefile. This typically
2168 includes everything deleted by
2169 <literal>distclean</literal>, plus more: C source files
2170 produced by Bison, tags tables, Info files, and so
2173 <para>One exception, however: <literal>make
2174 maintainer-clean</literal> should not delete
2175 <filename>configure</filename> even if
2176 <filename>configure</filename> can be remade using a rule
2177 in the <filename>Makefile</filename>. More generally,
2178 <literal>make maintainer-clean</literal> should not delete
2179 anything that needs to exist in order to run
2180 <filename>configure</filename> and then begin to build the
2186 <term><literal>check</literal></term>
2188 <para>run the test suite.</para>
2193 <para>All of these standard targets automatically recurse into
2194 sub-directories. Certain other standard targets do not:</para>
2198 <term><literal>configure</literal></term>
2200 <para>is only available in the root directory
2201 <constant>$(FPTOOLS_TOP)</constant>; it has
2202 been discussed in <XRef
2203 LinkEnd="sec-build-config">.</para>
2208 <term><literal>depend</literal></term>
2210 <para>make a <filename>.depend</filename> file in each
2211 directory that needs it. This <filename>.depend</filename>
2212 file contains mechanically-generated dependency
2213 information; for example, suppose a directory contains a
2214 Haskell source module <filename>Foo.lhs</filename> which
2215 imports another module <literal>Baz</literal>. Then the
2216 generated <filename>.depend</filename> file will contain
2217 the dependency:</para>
2223 <para>which says that the object file
2224 <filename>Foo.o</filename> depends on the interface file
2225 <filename>Baz.hi</filename> generated by compiling module
2226 <literal>Baz</literal>. The <filename>.depend</filename>
2227 file is automatically included by every Makefile.</para>
2232 <term><literal>binary-dist</literal></term>
2234 <para>make a binary distribution. This is the target we
2235 use to build the binary distributions of GHC and
2241 <term><literal>dist</literal></term>
2243 <para>make a source distribution. Note that this target
2244 does “make distclean” as part of its work;
2245 don't use it if you want to keep what you've built.</para>
2250 <para>Most <filename>Makefile</filename>s have targets other
2251 than these. You can discover them by looking in the
2252 <filename>Makefile</filename> itself.</para>
2256 <title>Using a project from the build tree</title>
2258 <para>If you want to build GHC (say) and just use it direct from
2259 the build tree without doing <literal>make install</literal>
2260 first, you can run the in-place driver script:
2261 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2263 <para> Do <emphasis>NOT</emphasis> use
2264 <filename>ghc/compiler/ghc</filename>, or
2265 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2266 scripts intended for installation, and contain hard-wired paths
2267 to the installed libraries, rather than the libraries in the
2270 <para>Happy can similarly be run from the build tree, using
2271 <filename>happy/src/happy-inplace</filename>, and similarly for
2272 Alex and Haddock.</para>
2276 <title>Fast Making</title>
2278 <indexterm><primary>fastmake</primary></indexterm>
2279 <indexterm><primary>dependencies, omitting</primary></indexterm>
2280 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2282 <para>Sometimes the dependencies get in the way: if you've made
2283 a small change to one file, and you're absolutely sure that it
2284 won't affect anything else, but you know that
2285 <command>make</command> is going to rebuild everything anyway,
2286 the following hack may be useful:</para>
2292 <para>This tells the make system to ignore dependencies and just
2293 build what you tell it to. In other words, it's equivalent to
2294 temporarily removing the <filename>.depend</filename> file in
2295 the current directory (where <command>mkdependHS</command> and
2296 friends store their dependency information).</para>
2298 <para>A bit of history: GHC used to come with a
2299 <command>fastmake</command> script that did the above job, but
2300 GNU make provides the features we need to do it without
2301 resorting to a script. Also, we've found that fastmaking is
2302 less useful since the advent of GHC's recompilation checker (see
2303 the User's Guide section on "Separate Compilation").</para>
2307 <sect1 id="sec-makefile-arch">
2308 <title>The <filename>Makefile</filename> architecture</title>
2309 <indexterm><primary>makefile architecture</primary></indexterm>
2311 <para><command>make</command> is great if everything
2312 works—you type <command>gmake install</command> and lo! the
2313 right things get compiled and installed in the right places. Our
2314 goal is to make this happen often, but somehow it often doesn't;
2315 instead some weird error message eventually emerges from the
2316 bowels of a directory you didn't know existed.</para>
2318 <para>The purpose of this section is to give you a road-map to
2319 help you figure out what is going right and what is going
2323 <title>Debugging</title>
2325 <para>Debugging <filename>Makefile</filename>s is something of a
2326 black art, but here's a couple of tricks that we find
2327 particularly useful. The following command allows you to see
2328 the contents of any make variable in the context of the current
2329 <filename>Makefile</filename>:</para>
2331 <screen>$ make show VALUE=HS_SRCS</screen>
2333 <para>where you can replace <literal>HS_SRCS</literal> with the
2334 name of any variable you wish to see the value of.</para>
2336 <para>GNU make has a <option>-d</option> option which generates
2337 a dump of the decision procedure used to arrive at a conclusion
2338 about which files should be recompiled. Sometimes useful for
2339 tracking down problems with superfluous or missing
2340 recompilations.</para>
2344 <title>A small project</title>
2346 <para>To get started, let us look at the
2347 <filename>Makefile</filename> for an imaginary small
2348 <literal>fptools</literal> project, <literal>small</literal>.
2349 Each project in <literal>fptools</literal> has its own directory
2350 in <constant>FPTOOLS_TOP</constant>, so the
2351 <literal>small</literal> project will have its own directory
2352 <constant>FPOOLS_TOP/small/</constant>. Inside the
2353 <filename>small/</filename> directory there will be a
2354 <filename>Makefile</filename>, looking something like
2357 <indexterm><primary>Makefile, minimal</primary></indexterm>
2360 # Makefile for fptools project "small"
2363 include $(TOP)/mk/boilerplate.mk
2365 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2368 include $(TOP)/target.mk
2371 <para>this <filename>Makefile</filename> has three
2376 <para>The first section includes
2379 One of the most important
2380 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2381 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2386 a file of “boilerplate” code from the level
2387 above (which in this case will be
2388 <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2389 As its name suggests, <filename>boilerplate.mk</filename>
2390 consists of a large quantity of standard
2391 <filename>Makefile</filename> code. We discuss this
2392 boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
2393 <indexterm><primary>include, directive in
2394 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2395 inclusion</primary></indexterm></para>
2397 <para>Before the <literal>include</literal> statement, you
2398 must define the <command>make</command> variable
2399 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2400 to be the directory containing the <filename>mk</filename>
2401 directory in which the <filename>boilerplate.mk</filename>
2402 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2405 include ../mk/boilerplate.mk # NO NO NO
2409 <para>Why? Because the <filename>boilerplate.mk</filename>
2410 file needs to know where it is, so that it can, in turn,
2411 <literal>include</literal> other files. (Unfortunately,
2412 when an <literal>include</literal>d file does an
2413 <literal>include</literal>, the filename is treated relative
2414 to the directory in which <command>gmake</command> is being
2415 run, not the directory in which the
2416 <literal>include</literal>d sits.) In general,
2417 <emphasis>every file <filename>foo.mk</filename> assumes
2419 <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
2420 refers to itself.</emphasis> It is up to the
2421 <filename>Makefile</filename> doing the
2422 <literal>include</literal> to ensure this is the case.</para>
2424 <para>Files intended for inclusion in other
2425 <filename>Makefile</filename>s are written to have the
2426 following property: <emphasis>after
2427 <filename>foo.mk</filename> is <literal>include</literal>d,
2428 it leaves <constant>TOP</constant> containing the same value
2429 as it had just before the <literal>include</literal>
2430 statement</emphasis>. In our example, this invariant
2431 guarantees that the <literal>include</literal> for
2432 <filename>target.mk</filename> will look in the same
2433 directory as that for <filename>boilerplate.mk</filename>.</para>
2437 <para> The second section defines the following standard
2438 <command>make</command> variables:
2439 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2440 (the source files from which is to be built), and
2441 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2442 (the executable binary to be built). We will discuss in
2443 more detail what the “standard variables” are,
2444 and how they affect what happens, in <XRef
2445 LinkEnd="sec-targets">.</para>
2447 <para>The definition for <constant>SRCS</constant> uses the
2448 useful GNU <command>make</command> construct
2449 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2450 which expands to a list of all the files matching the
2451 pattern <literal>pat</literal> in the current directory. In
2452 this example, <constant>SRCS</constant> is set to the list
2453 of all the <filename>.lhs</filename> and
2454 <filename>.c</filename> files in the directory. (Let's
2455 suppose there is one of each, <filename>Foo.lhs</filename>
2456 and <filename>Baz.c</filename>.)</para>
2460 <para>The last section includes a second file of standard
2462 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2463 It contains the rules that tell <command>gmake</command> how
2464 to make the standard targets (<Xref
2465 LinkEnd="sec-standard-targets">). Why, you ask, can't this
2466 standard code be part of
2467 <filename>boilerplate.mk</filename>? Good question. We
2468 discuss the reason later, in <Xref
2469 LinkEnd="sec-boiler-arch">.</para>
2471 <para>You do not <emphasis>have</emphasis> to
2472 <literal>include</literal> the
2473 <filename>target.mk</filename> file. Instead, you can write
2474 rules of your own for all the standard targets. Usually,
2475 though, you will find quite a big payoff from using the
2476 canned rules in <filename>target.mk</filename>; the price
2477 tag is that you have to understand what canned rules get
2478 enabled, and what they do (<Xref
2479 LinkEnd="sec-targets">).</para>
2483 <para>In our example <filename>Makefile</filename>, most of the
2484 work is done by the two <literal>include</literal>d files. When
2485 you say <command>gmake all</command>, the following things
2490 <para><command>gmake</command> figures out that the object
2491 files are <filename>Foo.o</filename> and
2492 <filename>Baz.o</filename>.</para>
2496 <para>It uses a boilerplate pattern rule to compile
2497 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2498 using a Haskell compiler. (Which one? That is set in the
2499 build configuration.)</para>
2503 <para>It uses another standard pattern rule to compile
2504 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2505 using a C compiler. (Ditto.)</para>
2509 <para>It links the resulting <filename>.o</filename> files
2510 together to make <literal>small</literal>, using the Haskell
2511 compiler to do the link step. (Why not use
2512 <command>ld</command>? Because the Haskell compiler knows
2513 what standard libraries to link in. How did
2514 <command>gmake</command> know to use the Haskell compiler to
2515 do the link, rather than the C compiler? Because we set the
2516 variable <constant>HS_PROG</constant> rather than
2517 <constant>C_PROG</constant>.)</para>
2521 <para>All <filename>Makefile</filename>s should follow the above
2522 three-section format.</para>
2526 <title>A larger project</title>
2528 <para>Larger projects are usually structured into a number of
2529 sub-directories, each of which has its own
2530 <filename>Makefile</filename>. (In very large projects, this
2531 sub-structure might be iterated recursively, though that is
2532 rare.) To give you the idea, here's part of the directory
2533 structure for the (rather large) GHC project:</para>
2543 ...source files for documentation...
2546 ...source files for driver...
2549 parser/...source files for parser...
2550 renamer/...source files for renamer...
2554 <para>The sub-directories <filename>docs</filename>,
2555 <filename>driver</filename>, <filename>compiler</filename>, and
2556 so on, each contains a sub-component of GHC, and each has its
2557 own <filename>Makefile</filename>. There must also be a
2558 <filename>Makefile</filename> in
2559 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
2560 It does most of its work by recursively invoking
2561 <command>gmake</command> on the <filename>Makefile</filename>s
2562 in the sub-directories. We say that
2563 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2564 <filename>Makefile</filename></emphasis>, because it does little
2565 except organise its children, while the
2566 <filename>Makefile</filename>s in the sub-directories are all
2567 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2568 principle the sub-directories might themselves contain a
2569 non-leaf <filename>Makefile</filename> and several
2570 sub-sub-directories, but that does not happen in GHC.)</para>
2572 <para>The <filename>Makefile</filename> in
2573 <filename>ghc/compiler</filename> is considered a leaf
2574 <filename>Makefile</filename> even though the
2575 <filename>ghc/compiler</filename> has sub-directories, because
2576 these sub-directories do not themselves have
2577 <filename>Makefile</filename>s in them. They are just used to
2578 structure the collection of modules that make up GHC, but all
2579 are managed by the single <filename>Makefile</filename> in
2580 <filename>ghc/compiler</filename>.</para>
2582 <para>You will notice that <filename>ghc/</filename> also
2583 contains a directory <filename>ghc/mk/</filename>. It contains
2584 GHC-specific <filename>Makefile</filename> boilerplate code.
2585 More precisely:</para>
2589 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2590 at the top of <filename>ghc/Makefile</filename>, and of all
2591 the leaf <filename>Makefile</filename>s in the
2592 sub-directories. It in turn <literal>include</literal>s the
2593 main boilerplate file
2594 <filename>mk/boilerplate.mk</filename>.</para>
2598 <para><filename>ghc/mk/target.mk</filename> is
2599 <literal>include</literal>d at the bottom of
2600 <filename>ghc/Makefile</filename>, and of all the leaf
2601 <filename>Makefile</filename>s in the sub-directories. It
2602 in turn <literal>include</literal>s the file
2603 <filename>mk/target.mk</filename>.</para>
2607 <para>So these two files are the place to look for GHC-wide
2608 customisation of the standard boilerplate.</para>
2611 <sect2 id="sec-boiler-arch">
2612 <title>Boilerplate architecture</title>
2613 <indexterm><primary>boilerplate architecture</primary></indexterm>
2615 <para>Every <filename>Makefile</filename> includes a
2616 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2617 file at the top, and
2618 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2619 file at the bottom. In this section we discuss what is in these
2620 files, and why there have to be two of them. In general:</para>
2624 <para><filename>boilerplate.mk</filename> consists of:</para>
2628 <para><emphasis>Definitions of millions of
2629 <command>make</command> variables</emphasis> that
2630 collectively specify the build configuration. Examples:
2631 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2632 the options to feed to the Haskell compiler;
2633 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2634 the sub-directories to enable within the
2635 <literal>nofib</literal> project;
2636 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2637 the name of the Haskell compiler to use when compiling
2638 GHC in the <literal>ghc</literal> project.</para>
2642 <para><emphasis>Standard pattern rules</emphasis> that
2643 tell <command>gmake</command> how to construct one file
2644 from another.</para>
2648 <para><filename>boilerplate.mk</filename> needs to be
2649 <literal>include</literal>d at the <emphasis>top</emphasis>
2650 of each <filename>Makefile</filename>, so that the user can
2651 replace the boilerplate definitions or pattern rules by
2652 simply giving a new definition or pattern rule in the
2653 <filename>Makefile</filename>. <command>gmake</command>
2654 simply takes the last definition as the definitive one.</para>
2656 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2657 definitions, it is also quite common to
2658 <emphasis>augment</emphasis> them. For example, a
2659 <filename>Makefile</filename> might say:</para>
2665 <para>thereby adding “<option>-O</option>” to
2667 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2671 <para><filename>target.mk</filename> contains
2672 <command>make</command> rules for the standard targets
2673 described in <Xref LinkEnd="sec-standard-targets">. These
2674 rules are selectively included, depending on the setting of
2675 certain <command>make</command> variables. These variables
2676 are usually set in the middle section of the
2677 <filename>Makefile</filename> between the two
2678 <literal>include</literal>s.</para>
2680 <para><filename>target.mk</filename> must be included at the
2681 end (rather than being part of
2682 <filename>boilerplate.mk</filename>) for several tiresome
2688 <para><command>gmake</command> commits target and
2689 dependency lists earlier than it should. For example,
2690 <FIlename>target.mk</FIlename> has a rule that looks
2694 $(HS_PROG) : $(OBJS)
2695 $(HC) $(LD_OPTS) $< -o $@
2698 <para>If this rule was in
2699 <filename>boilerplate.mk</filename> then
2700 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2702 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2703 would not have their final values at the moment
2704 <command>gmake</command> encountered the rule. Alas,
2705 <command>gmake</command> takes a snapshot of their
2706 current values, and wires that snapshot into the rule.
2707 (In contrast, the commands executed when the rule
2708 “fires” are only substituted at the moment
2709 of firing.) So, the rule must follow the definitions
2710 given in the <filename>Makefile</filename> itself.</para>
2714 <para>Unlike pattern rules, ordinary rules cannot be
2715 overriden or replaced by subsequent rules for the same
2716 target (at least, not without an error message).
2717 Including ordinary rules in
2718 <filename>boilerplate.mk</filename> would prevent the
2719 user from writing rules for specific targets in specific
2724 <para>There are a couple of other reasons I've
2725 forgotten, but it doesn't matter too much.</para>
2732 <sect2 id="sec-boiler">
2733 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2734 <indexterm><primary>boilerplate.mk</primary></indexterm>
2736 <para>If you look at
2737 <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
2738 you will find that it consists of the following sections, each
2739 held in a separate file:</para>
2743 <term><filename>config.mk</filename></term>
2744 <indexterm><primary>config.mk</primary></indexterm>
2746 <para>is the build configuration file we discussed at
2747 length in <Xref LinkEnd="sec-build-config">.</para>
2752 <term><filename>paths.mk</filename></term>
2753 <indexterm><primary>paths.mk</primary></indexterm>
2755 <para>defines <command>make</command> variables for
2756 pathnames and file lists. This file contains code for
2757 automatically compiling lists of source files and deriving
2758 lists of object files from those. The results can be
2759 overriden in the <filename>Makefile</filename>, but in
2760 most cases the automatic setup should do the right
2763 <para>The following variables may be set in the
2764 <filename>Makefile</filename> to affect how the automatic
2765 source file search is done:</para>
2769 <term><literal>ALL_DIRS</literal></term>
2770 <indexterm><primary><literal>ALL_DIRS</literal></primary>
2773 <para>Set to a list of directories to search in
2774 addition to the current directory for source
2780 <term><literal>EXCLUDE_SRCS</literal></term>
2781 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2784 <para>Set to a list of source files (relative to the
2785 current directory) to omit from the automatic
2786 search. The source searching machinery is clever
2787 enough to know that if you exclude a source file
2788 from which other sources are derived, then the
2789 derived sources should also be excluded. For
2790 example, if you set <literal>EXCLUDED_SRCS</literal>
2791 to include <filename>Foo.y</filename>, then
2792 <filename>Foo.hs</filename> will also be
2798 <term><literal>EXTRA_SRCS</literal></term>
2799 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2802 <para>Set to a list of extra source files (perhaps
2803 in directories not listed in
2804 <literal>ALL_DIRS</literal>) that should be
2810 <para>The results of the automatic source file search are
2811 placed in the following make variables:</para>
2815 <term><literal>SRCS</literal></term>
2816 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2818 <para>All source files found, sorted and without
2819 duplicates, including those which might not exist
2820 yet but will be derived from other existing sources.
2821 <literal>SRCS</literal> <emphasis>can</emphasis> be
2822 overriden if necessary, in which case the variables
2823 below will follow suit.</para>
2828 <term><literal>HS_SRCS</literal></term>
2829 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2831 <para>all Haskell source files in the current
2832 directory, including those derived from other source
2833 files (eg. Happy sources also give rise to Haskell
2839 <term><literal>HS_OBJS</literal></term>
2840 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2842 <para>Object files derived from
2843 <literal>HS_SRCS</literal>.</para>
2848 <term><literal>HS_IFACES</literal></term>
2849 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2851 <para>Interface files (<literal>.hi</literal> files)
2852 derived from <literal>HS_SRCS</literal>.</para>
2857 <term><literal>C_SRCS</literal></term>
2858 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2860 <para>All C source files found.</para>
2865 <term><literal>C_OBJS</literal></term>
2866 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2868 <para>Object files derived from
2869 <literal>C_SRCS</literal>.</para>
2874 <term><literal>SCRIPT_SRCS</literal></term>
2875 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2877 <para>All script source files found
2878 (<literal>.lprl</literal> files).</para>
2883 <term><literal>SCRIPT_OBJS</literal></term>
2884 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2886 <para><quote>object</quote> files derived from
2887 <literal>SCRIPT_SRCS</literal>
2888 (<literal>.prl</literal> files).</para>
2893 <term><literal>HSC_SRCS</literal></term>
2894 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2896 <para>All <literal>hsc2hs</literal> source files
2897 (<literal>.hsc</literal> files).</para>
2902 <term><literal>HAPPY_SRCS</literal></term>
2903 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2905 <para>All <literal>happy</literal> source files
2906 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2911 <term><literal>OBJS</literal></term>
2912 <indexterm><primary>OBJS</primary></indexterm>
2914 <para>the concatenation of
2915 <literal>$(HS_OBJS)</literal>,
2916 <literal>$(C_OBJS)</literal>, and
2917 <literal>$(SCRIPT_OBJS)</literal>.</para>
2922 <para>Any or all of these definitions can easily be
2923 overriden by giving new definitions in your
2924 <filename>Makefile</filename>.</para>
2926 <para>What, exactly, does <filename>paths.mk</filename>
2927 consider a <quote>source file</quote> to be? It's based
2928 on the file's suffix (e.g. <filename>.hs</filename>,
2929 <filename>.lhs</filename>, <filename>.c</filename>,
2930 <filename>.hy</filename>, etc), but this is the kind of
2931 detail that changes, so rather than enumerate the source
2932 suffices here the best thing to do is to look in
2933 <filename>paths.mk</filename>.</para>
2938 <term><filename>opts.mk</filename></term>
2939 <indexterm><primary>opts.mk</primary></indexterm>
2941 <para>defines <command>make</command> variables for option
2942 strings to pass to each program. For example, it defines
2943 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2944 the option strings to pass to the Haskell compiler. See
2945 <Xref LinkEnd="sec-suffix">.</para>
2950 <term><filename>suffix.mk</filename></term>
2951 <indexterm><primary>suffix.mk</primary></indexterm>
2953 <para>defines standard pattern rules—see <Xref
2954 LinkEnd="sec-suffix">.</para>
2959 <para>Any of the variables and pattern rules defined by the
2960 boilerplate file can easily be overridden in any particular
2961 <filename>Makefile</filename>, because the boilerplate
2962 <literal>include</literal> comes first. Definitions after this
2963 <literal>include</literal> directive simply override the default
2964 ones in <filename>boilerplate.mk</filename>.</para>
2967 <sect2 id="sec-suffix">
2968 <title>Pattern rules and options</title>
2969 <indexterm><primary>Pattern rules</primary></indexterm>
2972 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2973 defines standard <emphasis>pattern rules</emphasis> that say how
2974 to build one kind of file from another, for example, how to
2975 build a <filename>.o</filename> file from a
2976 <filename>.c</filename> file. (GNU <command>make</command>'s
2977 <emphasis>pattern rules</emphasis> are more powerful and easier
2978 to use than Unix <command>make</command>'s <emphasis>suffix
2979 rules</emphasis>.)</para>
2981 <para>Almost all the rules look something like this:</para>
2986 $(CC) $(CC_OPTS) -c $< -o $@
2989 <para>Here's how to understand the rule. It says that
2990 <emphasis>something</emphasis><filename>.o</filename> (say
2991 <filename>Foo.o</filename>) can be built from
2992 <emphasis>something</emphasis><filename>.c</filename>
2993 (<filename>Foo.c</filename>), by invoking the C compiler (path
2994 name held in <constant>$(CC)</constant>), passing to it
2995 the options <constant>$(CC_OPTS)</constant> and
2996 the rule's dependent file of the rule
2997 <literal>$<</literal> (<filename>Foo.c</filename> in
2998 this case), and putting the result in the rule's target
2999 <literal>$@</literal> (<filename>Foo.o</filename> in this
3002 <para>Every program is held in a <command>make</command>
3003 variable defined in <filename>mk/config.mk</filename>—look
3004 in <filename>mk/config.mk</filename> for the complete list. One
3005 important one is the Haskell compiler, which is called
3006 <constant>$(HC)</constant>.</para>
3008 <para>Every program's options are are held in a
3009 <command>make</command> variables called
3010 <constant><prog>_OPTS</constant>. the
3011 <constant><prog>_OPTS</constant> variables are
3012 defined in <filename>mk/opts.mk</filename>. Almost all of them
3013 are defined like this:</para>
3016 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
3019 <para>The four variables from which
3020 <constant>CC_OPTS</constant> is built have the following
3025 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3027 <para>options passed to all C compilations.</para>
3032 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3034 <para>options passed to C compilations for way
3035 <literal><way></literal>. For example,
3036 <constant>WAY_mp_CC_OPTS</constant>
3037 gives options to pass to the C compiler when compiling way
3038 <literal>mp</literal>. The variable
3039 <constant>WAY_CC_OPTS</constant> holds
3040 options to pass to the C compiler when compiling the
3041 standard way. (<Xref LinkEnd="sec-ways"> dicusses
3042 multi-way compilation.)</para>
3047 <term><constant><module>_CC_OPTS</constant>:</term>
3049 <para>options to pass to the C compiler that are specific
3050 to module <literal><module></literal>. For example,
3051 <constant>SMap_CC_OPTS</constant> gives the
3052 specific options to pass to the C compiler when compiling
3053 <filename>SMap.c</filename>.</para>
3058 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3060 <para>extra options to pass to all C compilations. This
3061 is intended for command line use, thus:</para>
3064 gmake libHS.a EXTRA_CC_OPTS="-v"
3071 <sect2 id="sec-targets">
3072 <title>The main <filename>mk/target.mk</filename> file</title>
3073 <indexterm><primary>target.mk</primary></indexterm>
3075 <para><filename>target.mk</filename> contains canned rules for
3076 all the standard targets described in <Xref
3077 LinkEnd="sec-standard-targets">. It is complicated by the fact
3078 that you don't want all of these rules to be active in every
3079 <filename>Makefile</filename>. Rather than have a plethora of
3080 tiny files which you can include selectively, there is a single
3081 file, <filename>target.mk</filename>, which selectively includes
3082 rules based on whether you have defined certain variables in
3083 your <filename>Makefile</filename>. This section explains what
3084 rules you get, what variables control them, and what the rules
3085 do. Hopefully, you will also get enough of an idea of what is
3086 supposed to happen that you can read and understand any weird
3087 special cases yourself.</para>
3091 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3093 <para>If <constant>HS_PROG</constant> is defined,
3094 you get rules with the following targets:</para>
3098 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3100 <para>itself. This rule links
3101 <constant>$(OBJS)</constant> with the Haskell
3102 runtime system to get an executable called
3103 <constant>$(HS_PROG)</constant>.</para>
3108 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3111 <constant>$(HS_PROG)</constant> in
3112 <constant>$(bindir)</constant>.</para>
3121 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3123 <para>is similar to <constant>HS_PROG</constant>,
3124 except that the link step links
3125 <constant>$(C_OBJS)</constant> with the C
3126 runtime system.</para>
3131 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3133 <para>is similar to <constant>HS_PROG</constant>,
3134 except that it links
3135 <constant>$(LIB_OBJS)</constant> to make the
3136 library archive <constant>$(LIBRARY)</constant>,
3137 and <literal>install</literal> installs it in
3138 <constant>$(libdir)</constant>.</para>
3143 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3145 <para>…</para>
3150 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3152 <para>…</para>
3157 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3159 <para>If <constant>HS_SRCS</constant> is defined
3160 and non-empty, a rule for the target
3161 <literal>depend</literal> is included, which generates
3162 dependency information for Haskell programs. Similarly
3163 for <constant>C_SRCS</constant>.</para>
3168 <para>All of these rules are “double-colon” rules,
3172 install :: $(HS_PROG)
3173 ...how to install it...
3176 <para>GNU <command>make</command> treats double-colon rules as
3177 separate entities. If there are several double-colon rules for
3178 the same target it takes each in turn and fires it if its
3179 dependencies say to do so. This means that you can, for
3180 example, define both <constant>HS_PROG</constant> and
3181 <constant>LIBRARY</constant>, which will generate two rules for
3182 <literal>install</literal>. When you type <command>gmake
3183 install</command> both rules will be fired, and both the program
3184 and the library will be installed, just as you wanted.</para>
3187 <sect2 id="sec-subdirs">
3188 <title>Recursion</title>
3189 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3190 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3192 <para>In leaf <filename>Makefile</filename>s the variable
3193 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3194 is undefined. In non-leaf <filename>Makefile</filename>s,
3195 <constant>SUBDIRS</constant> is set to the list of
3196 sub-directories that contain subordinate
3197 <filename>Makefile</filename>s. <emphasis>It is up to you to
3198 set <constant>SUBDIRS</constant> in the
3199 <filename>Makefile</filename>.</emphasis> There is no automation
3200 here—<constant>SUBDIRS</constant> is too important to
3203 <para>When <constant>SUBDIRS</constant> is defined,
3204 <filename>target.mk</filename> includes a rather neat rule for
3205 the standard targets (<Xref LinkEnd="sec-standard-targets"> that
3206 simply invokes <command>make</command> recursively in each of
3207 the sub-directories.</para>
3209 <para><emphasis>These recursive invocations are guaranteed to
3210 occur in the order in which the list of directories is specified
3211 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3212 be important. For example, when you say <command>gmake
3213 boot</command> it can be important that the recursive invocation
3214 of <command>make boot</command> is done in one sub-directory
3215 (the include files, say) before another (the source files).
3216 Generally, put the most independent sub-directory first, and the
3217 most dependent last.</para>
3220 <sect2 id="sec-ways">
3221 <title>Way management</title>
3222 <indexterm><primary>way management</primary></indexterm>
3224 <para>We sometimes want to build essentially the same system in
3225 several different “ways”. For example, we want to build GHC's
3226 <literal>Prelude</literal> libraries with and without profiling,
3227 so that there is an appropriately-built library archive to link
3228 with when the user compiles his program. It would be possible
3229 to have a completely separate build tree for each such “way”,
3230 but it would be horribly bureaucratic, especially since often
3231 only parts of the build tree need to be constructed in multiple
3235 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3236 contains some clever magic to allow you to build several
3237 versions of a system; and to control locally how many versions
3238 are built and how they differ. This section explains the
3241 <para>The files for a particular way are distinguished by
3242 munging the suffix. The <quote>normal way</quote> is always
3243 built, and its files have the standard suffices
3244 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3245 In addition, you can build one or more extra ways, each
3246 distinguished by a <emphasis>way tag</emphasis>. The object
3247 files and interface files for one of these extra ways are
3248 distinguished by their suffix. For example, way
3249 <literal>mp</literal> has files
3250 <filename>.mp_o</filename> and
3251 <filename>.mp_hi</filename>. Library archives have their
3252 way tag the other side of the dot, for boring reasons; thus,
3253 <filename>libHS_mp.a</filename>.</para>
3255 <para>A <command>make</command> variable called
3256 <constant>way</constant> holds the current way tag.
3257 <emphasis><constant>way</constant> is only ever set on the
3258 command line of <command>gmake</command></emphasis> (usually in
3259 a recursive invocation of <command>gmake</command> by the
3260 system). It is never set inside a
3261 <filename>Makefile</filename>. So it is a global constant for
3262 any one invocation of <command>gmake</command>. Two other
3263 <command>make</command> variables,
3264 <constant>way_</constant> and
3265 <constant>_way</constant> are immediately derived from
3266 <constant>$(way)</constant> and never altered. If
3267 <constant>way</constant> is not set, then neither are
3268 <constant>way_</constant> and
3269 <constant>_way</constant>, and the invocation of
3270 <command>make</command> will build the <quote>normal
3271 way</quote>. If <constant>way</constant> is set, then the other
3272 two variables are set in sympathy. For example, if
3273 <constant>$(way)</constant> is “<literal>mp</literal>”,
3274 then <constant>way_</constant> is set to
3275 “<literal>mp_</literal>” and
3276 <constant>_way</constant> is set to
3277 “<literal>_mp</literal>”. These three variables are
3278 then used when constructing file names.</para>
3280 <para>So how does <command>make</command> ever get recursively
3281 invoked with <constant>way</constant> set? There are two ways
3282 in which this happens:</para>
3286 <para>For some (but not all) of the standard targets, when
3287 in a leaf sub-directory, <command>make</command> is
3288 recursively invoked for each way tag in
3289 <constant>$(WAYS)</constant>. You set
3290 <constant>WAYS</constant> in the
3291 <filename>Makefile</filename> to the list of way tags you
3292 want these targets built for. The mechanism here is very
3293 much like the recursive invocation of
3294 <command>make</command> in sub-directories (<Xref
3295 LinkEnd="sec-subdirs">). It is up to you to set
3296 <constant>WAYS</constant> in your
3297 <filename>Makefile</filename>; this is how you control what
3298 ways will get built.</para>
3302 <para>For a useful collection of targets (such as
3303 <filename>libHS_mp.a</filename>,
3304 <filename>Foo.mp_o</filename>) there is a rule which
3305 recursively invokes <command>make</command> to make the
3306 specified target, setting the <constant>way</constant>
3307 variable. So if you say <command>gmake
3308 Foo.mp_o</command> you should see a recursive
3309 invocation <command>gmake Foo.mp_o way=mp</command>,
3310 and <emphasis>in this recursive invocation the pattern rule
3311 for compiling a Haskell file into a <filename>.o</filename>
3312 file will match</emphasis>. The key pattern rules (in
3313 <filename>suffix.mk</filename>) look like this:
3317 $(HC) $(HC_OPTS) $< -o $@
3324 <para>You can invoke <command>make</command> with a
3325 particular <literal>way</literal> setting yourself, in order
3326 to build files related to a particular
3327 <literal>way</literal> in the current directory. eg.
3333 will build files for the profiling way only in the current
3340 <title>When the canned rule isn't right</title>
3342 <para>Sometimes the canned rule just doesn't do the right thing.
3343 For example, in the <literal>nofib</literal> suite we want the
3344 link step to print out timing information. The thing to do here
3345 is <emphasis>not</emphasis> to define
3346 <constant>HS_PROG</constant> or
3347 <constant>C_PROG</constant>, and instead define a special
3348 purpose rule in your own <filename>Makefile</filename>. By
3349 using different variable names you will avoid the canned rules
3350 being included, and conflicting with yours.</para>
3354 <sect1 id="building-docs">
3355 <title>Building the documentation</title>
3357 <sect2 id="pre-supposed-doc-tools">
3358 <title>Tools for building the Documentation</title>
3360 <para>The following additional tools are required if you want to
3361 format the documentation that comes with the
3362 <literal>fptools</literal> projects:</para>
3366 <term>DocBook</term>
3367 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3368 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3370 <para>Much of our documentation is written in SGML, using
3371 the DocBook DTD. Instructions on installing and
3372 configuring the DocBook tools are below.</para>
3378 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3379 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3381 <para>A decent TeX distribution is required if you want to
3382 produce printable documentation. We recomment teTeX,
3383 which includes just about everything you need.</para>
3388 <term>Haddock</term>
3389 <indexterm><primary>Haddock</primary>
3392 <para>Haddock is a Haskell documentation tool that we use
3393 for automatically generating documentation from the
3394 library source code. It is an <literal>fptools</literal>
3395 project in itself. To build documentation for the
3396 libraries (<literal>fptools/libraries</literal>) you
3397 should check out and build Haddock in
3398 <literal>fptools/haddock</literal>. Haddock requires GHC
3406 <title>Installing the DocBook tools</title>
3409 <title>Installing the DocBook tools on Linux</title>
3411 <para>If you're on a recent RedHat system (7.0+), you probably
3412 have working DocBook tools already installed. The configure
3413 script should detect your setup and you're away.</para>
3415 <para>If you don't have DocBook tools installed, and you are
3416 using a system that can handle RedHat RPM packages, you can
3417 probably use the <ULink
3418 URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3419 DocBook tools</ULink>, which is the most shrink-wrapped SGML
3420 suite that we could find. You need all the RPMs except for
3421 psgml (i.e. <Filename>docbook</Filename>,
3422 <Filename>jade</Filename>, <Filename>jadetex</Filename>,
3423 <Filename>sgmlcommon</Filename> and
3424 <Filename>stylesheets</Filename>). Note that most of these
3425 RPMs are architecture neutral, so are likely to be found in a
3426 <Filename>noarch</Filename> directory. The SuSE RPMs also
3427 work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
3428 (7.0 and later should be OK), but they are easy to fix: just
3430 <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
3431 to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
3435 <title>Installing DocBook on FreeBSD</title>
3437 <para>On FreeBSD systems, the easiest way to get DocBook up
3438 and running is to install it from the ports tree or a
3439 pre-compiled package (packages are available from your local
3440 FreeBSD mirror site).</para>
3442 <para>To use the ports tree, do this:
3444 $ cd /usr/ports/textproc/docproj
3447 This installs the FreeBSD documentation project tools, which
3448 includes everything needed to format the GHC
3449 documentation.</para>
3453 <title>Installing from binaries on Windows</title>
3455 <Para>It's a good idea to use Norman Walsh's <ULink
3456 URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3457 notes</ULink> as a guide. You should get version 3.1 of
3458 DocBook, and note that his file <Filename>test.sgm</Filename>
3459 won't work, as it needs version 3.0. You should unpack Jade
3460 into <Filename>\Jade</Filename>, along with the entities,
3461 DocBook into <Filename>\docbook</Filename>, and the DocBook
3462 stylesheets into <Filename>\docbook\stylesheets</Filename> (so
3463 they actually end up in
3464 <Filename>\docbook\stylesheets\docbook</Filename>).</para>
3469 <title>Installing the DocBook tools from source</title>
3474 <para>Install <ULink
3475 URL="http://openjade.sourceforge.net/">OpenJade</ULink>
3476 (Windows binaries are available as well as sources). If you
3477 want DVI, PS, or PDF then install JadeTeX from the
3478 <Filename>dsssl</Filename> subdirectory. (If you get the
3482 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
3485 your version of <Command>hyperref</Command> is out of date;
3486 download it from CTAN
3487 (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
3488 and make it, ensuring that you have first removed or renamed
3489 your old copy. If you start getting file not found errors
3490 when making the test for <Command>hyperref</Command>, you
3491 can abort at that point and proceed straight to
3492 <Command>make install</Command>, or enter them as
3493 <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
3495 <para>Make links from <Filename>virtex</Filename> to
3496 <Filename>jadetex</Filename> and
3497 <Filename>pdfvirtex</Filename> to
3498 <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
3499 and PDF output will not work). Copy
3500 <Filename>dsssl/*.{dtd,dsl}</Filename> and
3501 <Filename>catalog</Filename> to
3502 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3506 <title>DocBook and the DocBook stylesheets</title>
3508 <para>Get a Zip of <ULink
3509 URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
3510 and install the contents in
3511 <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
3513 <para>Get the <ULink
3514 URL="http://nwalsh.com/docbook/dsssl/">DocBook
3515 stylesheets</ULink> and install in
3516 <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
3517 (thereby creating a subdirectory docbook). For indexing,
3518 copy or link <Filename>collateindex.pl</Filename> from the
3519 DocBook stylesheets archive in <Filename>bin</Filename> into
3520 a directory on your <Constant>PATH</Constant>.</para>
3522 <para>Download the <ULink
3523 URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3524 entities</ULink> into
3525 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3531 <title>Configuring the DocBook tools</title>
3533 <Para>Once the DocBook tools are installed, the configure script
3534 will detect them and set up the build system accordingly. If you
3535 have a system that isn't supported, let us know, and we'll try
3540 <title>Remaining problems</title>
3542 <para>If you install from source, you'll get a pile of warnings
3545 <Screen>DTDDECL catalog entries are not supported</Screen>
3547 every time you build anything. These can safely be ignored, but
3548 if you find them tedious you can get rid of them by removing all
3549 the <Constant>DTDDECL</Constant> entries from
3550 <Filename>docbook.cat</Filename>.</para>
3554 <title>Building the documentation</title>
3556 <para>To build documentation in a certain format, you can
3557 say, for example,</para>
3563 <para>to build HTML documentation below the current directory.
3564 The available formats are: <literal>dvi</literal>,
3565 <literal>ps</literal>, <literal>pdf</literal>,
3566 <literal>html</literal>, and <literal>rtf</literal>. Note that
3567 not all documentation can be built in all of these formats: HTML
3568 documentation is generally supported everywhere, and DocBook
3569 documentation might support the other formats (depending on what
3570 other tools you have installed).</para>
3572 <para>All of these targets are recursive; that is, saying
3573 <literal>make html</literal> will make HTML docs for all the
3574 documents recursively below the current directory.</para>
3576 <para>Because there are many different formats that the DocBook
3577 documentation can be generated in, you have to select which ones
3578 you want by setting the <literal>SGMLDocWays</literal> variable
3579 to a list of them. For example, in
3580 <filename>build.mk</filename> you might have a line:</para>
3583 SGMLDocWays = html ps
3586 <para>This will cause the documentation to be built in the requested
3587 formats as part of the main build (the default is not to build
3588 any documentation at all).</para>
3592 <title>Installing the documentation</title>
3594 <para>To install the documentation, use:</para>
3600 <para>This will install the documentation into
3601 <literal>$(datadir)</literal> (which defaults to
3602 <literal>$(prefix)/share</literal>). The exception is HTML
3603 documentation, which goes into
3604 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3606 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3607 to a list of formats, the <literal>install-docs</literal> target
3608 won't do anything for SGML documentation.</para>
3614 <sect1 id="sec-porting-ghc">
3615 <title>Porting GHC</title>
3617 <para>This section describes how to port GHC to a currenly
3618 unsupported platform. There are two distinct
3619 possibilities:</para>
3623 <para>The hardware architecture for your system is already
3624 supported by GHC, but you're running an OS that isn't
3625 supported (or perhaps has been supported in the past, but
3626 currently isn't). This is the easiest type of porting job,
3627 but it still requires some careful bootstrapping. Proceed to
3628 <xref linkend="sec-booting-from-hc">.</para>
3632 <para>Your system's hardware architecture isn't supported by
3633 GHC. This will be a more difficult port (though by comparison
3634 perhaps not as difficult as porting gcc). Proceed to <xref
3635 linkend="unregisterised-porting">.</para>
3639 <sect2 id="sec-booting-from-hc">
3640 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3642 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3643 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3644 <indexterm><primary>porting GHC</primary></indexterm>
3646 <para>Bootstrapping GHC on a system without GHC already
3647 installed is achieved by taking the intermediate C files (known
3648 as HC files) from a GHC compilation on a supported system to the
3649 target machine, and compiling them using gcc to get a working
3652 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3653 from C. We recommend using GHC 6.0.1 or
3654 later.</emphasis></para>
3656 <para>HC files are platform-dependent, so you have to get a set
3657 that were generated on similar hardware. There may be some
3658 supplied on the GHC download page, otherwise you'll have to
3659 compile some up yourself, or start from
3660 <emphasis>unregisterised</emphasis> HC files - see <xref
3661 linkend="unregisterised-porting">.</para>
3663 <para>The following steps should result in a working GHC build
3664 with full libraries:</para>
3668 <para>Unpack the HC files on top of a fresh source tree
3669 (make sure the source tree version matches the version of
3670 the HC files <emphasis>exactly</emphasis>!). This will
3671 place matching <filename>.hc</filename> files next to the
3672 corresponding Haskell source (<filename>.hs</filename> or
3673 <filename>.lhs</filename>) in the compiler subdirectory
3674 <filename>ghc/compiler</filename> and in the libraries
3675 (subdirectories of <filename>hslibs</filename> and
3676 <literal>libraries</literal>).</para>
3680 <para>The actual build process is fully automated by the
3681 <filename>hc-build</filename> script located in the
3682 <filename>distrib</filename> directory. If you eventually
3683 want to install GHC into the directory
3684 <replaceable>dir</replaceable>, the following
3685 command will execute the whole build process (it won't
3686 install yet):</para>
3689 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3691 <indexterm><primary>--hc-build</primary></indexterm>
3693 <para>By default, the installation directory is
3694 <filename>/usr/local</filename>. If that is what you want,
3695 you may omit the argument to <filename>hc-build</filename>.
3696 Generally, any option given to <filename>hc-build</filename>
3697 is passed through to the configuration script
3698 <filename>configure</filename>. If
3699 <filename>hc-build</filename> successfully completes the
3700 build process, you can install the resulting system, as
3710 <sect2 id="unregisterised-porting">
3711 <title>Porting GHC to a new architecture</title>
3713 <para>The first step in porting to a new architecture is to get
3714 an <firstterm>unregisterised</firstterm> build working. An
3715 unregisterised build is one that compiles via vanilla C only.
3716 By contrast, a registerised build uses the following
3717 architecture-specific hacks for speed:</para>
3721 <para>Global register variables: certain abstract machine
3722 <quote>registers</quote> are mapped to real machine
3723 registers, depending on how many machine registers are
3725 <filename>ghc/includes/MachRegs.h</filename>).</para>
3729 <para>Assembly-mangling: when compiling via C, we feed the
3730 assembly generated by gcc though a Perl script known as the
3731 <firstterm>mangler</firstterm> (see
3732 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3733 mangler rearranges the assembly to support tail-calls and
3734 various other optimisations.</para>
3738 <para>In an unregisterised build, neither of these hacks are
3739 used — the idea is that the C code generated by the
3740 compiler should compile using gcc only. The lack of these
3741 optimisations costs about a factor of two in performance, but
3742 since unregisterised compilation is usually just a step on the
3743 way to a full registerised port, we don't mind too much.</para>
3745 <para>Notes on GHC portability in general: we've tried to stick
3746 to writing portable code in most parts of the system, so it
3747 should compile on any POSIXish system with gcc, but in our
3748 experience most systems differ from the standards in one way or
3749 another. Deal with any problems as they arise - if you get
3750 stuck, ask the experts on
3751 <email>glasgow-haskell-users@haskell.org</email>.</para>
3753 <para>Lots of useful information about the innards of GHC is
3754 available in the <ulink
3755 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3756 Commentary</ulink>, which might be helpful if you run into some
3757 code which needs tweaking for your system.</para>
3760 <title>Cross-compiling to produce an unregisterised GHC</title>
3762 <para>In this section, we explain how to bootstrap GHC on a
3763 new platform, using unregisterised intermediate C files. We
3764 haven't put a great deal of effort into automating this
3765 process, for two reasons: it is done very rarely, and the
3766 process usually requires human intervention to cope with minor
3767 porting issues anyway.</para>
3769 <para>The following step-by-step instructions should result in
3770 a fully working, albeit unregisterised, GHC. Firstly, you
3771 need a machine that already has a working GHC (we'll call this
3772 the <firstterm>host</firstterm> machine), in order to
3773 cross-compile the intermediate C files that we will use to
3774 bootstrap the compiler on the <firstterm>target</firstterm>
3779 <para>On the target machine:</para>
3783 <para>Unpack a source tree (preferably a released
3784 version). We will call the path to the root of this
3785 tree <replaceable>T</replaceable>.</para>
3790 $ cd <replaceable>T</replaceable>
3791 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
3794 <para>You might need to update
3795 <filename>configure.in</filename> to recognise the new
3796 architecture, and re-generate
3797 <filename>configure</filename> with
3798 <literal>autoreconf</literal>.</para>
3803 $ cd <replaceable>T</replaceable>/ghc/includes
3811 <para>On the host machine:</para>
3815 <para>Unpack a source tree (same released version). Call
3816 this directory <replaceable>H</replaceable>.</para>
3821 $ cd <replaceable>H</replaceable>
3828 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3829 with the following contents:</para>
3832 GhcUnregisterised = YES
3833 GhcLibHcOpts = -O -H32m -keep-hc-files
3836 GhcWithNativeCodeGen = NO
3837 GhcWithInterpreter = NO
3838 GhcStage1HcOpts = -O -H32m -fasm
3839 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3845 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3848 <para>change <literal>TARGETPLATFORM</literal>
3849 appropriately, and set the variables involving
3850 <literal>TARGET</literal> to the correct values for
3851 the target platform. This step is necessary because
3852 currently <literal>configure</literal> doesn't cope
3853 with specifying different values for the
3854 <literal>--host</literal> and
3855 <literal>--target</literal> flags.</para>
3858 <para>copy <literal>LeadingUnderscore</literal>
3859 setting from target.</para>
3866 <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
3868 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3869 Note that we are building on the host machine, using the
3870 target machine's <literal>config.h</literal> file. This
3871 is so that the intermediate C files generated here will
3872 be suitable for compiling on the target system.</para>
3877 <para>Touch <literal>config.h</literal>, just to make
3878 sure it doesn't get replaced during the build:</para>
3880 $ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
3884 <para>Now build the compiler:</para>
3886 $ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3887 $ cd <replaceable>H</replaceable>/ghc && make boot && make
3889 <para>Don't worry if the build falls over in the RTS, we
3890 don't need the RTS yet.</para>
3895 $ cd <replaceable>H</replaceable>/libraries
3896 $& make boot && make
3902 $ cd <replaceable>H</replaceable>/ghc
3903 $ make boot stage=2 && make stage=2
3909 $ cd <replaceable>H</replaceable>/ghc/utils
3911 $ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
3912 EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3918 $ cd <replaceable>H</replaceable>
3919 $ make hc-file-bundle Project=Ghc
3925 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3926 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3932 <para>On the target machine:</para>
3934 <para>At this stage we simply need to bootstrap a compiler
3935 from the intermediate C files we generated above. The
3936 process of bootstrapping from C files is automated by the
3937 script in <literal>distrib/hc-build</literal>, and is
3938 described in <xref linkend="sec-booting-from-hc">.</para>
3941 $ ./distrib/hc-build --enable-hc-boot-unregisterised
3944 <para>However, since this is a bootstrap on a new machine,
3945 the automated process might not run to completion the
3946 first time. For that reason, you might want to treat the
3947 <literal>hc-build</literal> script as a list of
3948 instructions to follow, rather than as a fully automated
3949 script. This way you'll be able to restart the process
3950 part-way through if you need to fix anything on the
3953 <para>Don't bother with running
3954 <literal>make install</literal> in the newly
3955 bootstrapped tree; just use the compiler in that tree to
3956 build a fresh compiler from scratch, this time without
3957 booting from C files. Before doing this, you might want
3958 to check that the bootstrapped compiler is generating
3959 working binaries:</para>
3963 main = putStrLn "Hello World!\n"
3965 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3970 <para>Once you have the unregisterised compiler up and
3971 running, you can use it to start a registerised port. The
3972 following sections describe the various parts of the
3973 system that will need architecture-specific tweaks in
3974 order to get a registerised build going.</para>
3981 <title>Porting the RTS</title>
3983 <para>The following files need architecture-specific code for a
3984 registerised build:</para>
3988 <term><filename>ghc/includes/MachRegs.h</filename></term>
3989 <indexterm><primary><filename>MachRegs.h</filename></primary>
3992 <para>Defines the STG-register to machine-register
3993 mapping. You need to know your platform's C calling
3994 convention, and which registers are generally available
3995 for mapping to global register variables. There are
3996 plenty of useful comments in this file.</para>
4000 <term><filename>ghc/includes/TailCalls.h</filename></term>
4001 <indexterm><primary><filename>TailCalls.h</filename></primary>
4004 <para>Macros that cooperate with the mangler (see <xref
4005 linkend="sec-mangler">) to make proper tail-calls
4010 <term><filename>ghc/rts/Adjustor.c</filename></term>
4011 <indexterm><primary><filename>Adjustor.c</filename></primary>
4015 <literal>foreign import "wrapper"</literal>
4017 <literal>foreign export dynamic</literal>).
4018 Not essential for getting GHC bootstrapped, so this file
4019 can be deferred until later if necessary.</para>
4023 <term><filename>ghc/rts/StgCRun.c</filename></term>
4024 <indexterm><primary><filename>StgCRun.c</filename></primary>
4027 <para>The little assembly layer between the C world and
4028 the Haskell world. See the comments and code for the
4029 other architectures in this file for pointers.</para>
4033 <term><filename>ghc/rts/MBlock.h</filename></term>
4034 <term><filename>ghc/rts/MBlock.c</filename></term>
4035 <indexterm><primary><filename>MBlock.h</filename></primary>
4037 <indexterm><primary><filename>MBlock.c</filename></primary>
4040 <para>These files are really OS-specific rather than
4041 architecture-specific. In <filename>MBlock.h</filename>
4042 is specified the absolute location at which the RTS
4043 should try to allocate memory on your platform (try to
4044 find an area which doesn't conflict with code or dynamic
4045 libraries). In <filename>Mblock.c</filename> you might
4046 need to tweak the call to <literal>mmap()</literal> for
4053 <sect3 id="sec-mangler">
4054 <title>The mangler</title>
4056 <para>The mangler is an evil Perl-script that rearranges the
4057 assembly code output from gcc to do two main things:</para>
4061 <para>Remove function prologues and epilogues, and all
4062 movement of the C stack pointer. This is to support
4063 tail-calls: every code block in Haskell code ends in an
4064 explicit jump, so we don't want the C-stack overflowing
4065 while we're jumping around between code blocks.</para>
4068 <para>Move the <firstterm>info table</firstterm> for a
4069 closure next to the entry code for that closure. In
4070 unregisterised code, info tables contain a pointer to the
4071 entry code, but in registerised compilation we arrange
4072 that the info table is shoved right up against the entry
4073 code, and addressed backwards from the entry code pointer
4074 (this saves a word in the info table and an extra
4075 indirection when jumping to the closure entry
4080 <para>The mangler is abstracted to a certain extent over some
4081 architecture-specific things such as the particular assembler
4082 directives used to herald symbols. Take a look at the
4083 definitions for other architectures and use these as a
4084 starting point.</para>
4088 <title>The native code generator</title>
4090 <para>The native code generator isn't essential to getting a
4091 registerised build going, but it's a desirable thing to have
4092 because it can cut compilation times in half. The native code
4093 generator is described in some detail in the <ulink
4094 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
4095 commentary</ulink>.</para>
4101 <para>To support GHCi, you need to port the dynamic linker
4102 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
4103 currently supports the ELF and PEi386 object file formats - if
4104 your platform uses one of these then things will be
4105 significantly easier. The majority of Unix platforms use the
4106 ELF format these days. Even so, there are some
4107 machine-specific parts of the ELF linker: for example, the
4108 code for resolving particular relocation types is
4109 machine-specific, so some porting of this code to your
4110 architecture will probaly be necessary.</para>
4112 <para>If your system uses a different object file format, then
4113 you have to write a linker — good luck!</para>
4119 <sect1 id="sec-build-pitfalls">
4120 <title>Known pitfalls in building Glasgow Haskell
4122 <indexterm><primary>problems, building</primary></indexterm>
4123 <indexterm><primary>pitfalls, in building</primary></indexterm>
4124 <indexterm><primary>building pitfalls</primary></indexterm></title>
4127 WARNINGS about pitfalls and known “problems”:
4136 One difficulty that comes up from time to time is running out of space
4137 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
4138 compensate for the vagaries of different sysadmin approaches to temp
4140 <indexterm><primary>tmp, running out of space in</primary></indexterm>
4142 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
4143 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
4146 The best way around it is to say
4149 export TMPDIR=<dir>
4152 in your <filename>build.mk</filename> file.
4153 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
4162 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
4163 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
4171 When compiling via C, you'll sometimes get “warning: assignment from
4172 incompatible pointer type” out of GCC. Harmless.
4179 Similarly, <command>ar</command>chiving warning messages like the following are not
4183 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
4184 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
4194 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
4195 get an “Out of heap space” error message. These can vary with the
4196 vagaries of different systems, it seems. The solution is simple:
4203 If you're compiling with GHC 4.00 or later, then the
4204 <emphasis>maximum</emphasis> heap size must have been reached. This
4205 is somewhat unlikely, since the maximum is set to 64M by default.
4206 Anyway, you can raise it with the
4207 <option>-optCrts-M<size></option> flag (add this flag to
4208 <constant><module>_HC_OPTS</constant>
4209 <command>make</command> variable in the appropriate
4210 <filename>Makefile</filename>).
4217 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4226 and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
4227 <constant><module>_HC_OPTS</constant>.)
4229 Alternatively, just cut to the chase:
4233 % make EXTRA_HC_OPTS=-optCrts-M128M
4242 If you try to compile some Haskell, and you get errors from GCC about
4243 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4244 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4246 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4247 this bug also suggests that you have an old GCC.
4255 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4259 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4260 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4262 ? # or, on some machines: ar s $i
4267 We'd be interested to know if this is still necessary.
4275 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4276 a bit from one Unix to another. One particular gotcha is macro calls
4281 SLIT("Hello, world")
4285 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4286 arguments, so you get
4290 :731: macro `SLIT' used with too many (2) args
4294 Alas, <command>cpp</command> doesn't tell you the offending file!
4296 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4307 <Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
4310 This section summarises how to get the utilities you need on your
4311 Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
4312 installing and running GHC may be found in the user guide. In general,
4313 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4314 You should read the GHC installation guide sections on Windows (in the user
4315 guide) before continuing to read these notes.
4319 <sect2 id="cygwin-and-mingw"><Title>Cygwin and MinGW</Title>
4321 <para> The Windows situation for building GHC is rather confusing. This section
4322 tries to clarify, and to establish terminology.</para>
4324 <sect3 id="ghc-mingw"><title>GHC-mingw</title>
4326 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4327 is a collection of header
4328 files and import libraries that allow one to use <command>gcc</command> and produce
4329 native Win32 programs that do not rely on any third-party DLLs. The
4330 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4331 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4334 <para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
4335 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4336 GHC compiles Haskell to C (or to
4337 assembly code), and then invokes these MinGW tools to generate an executable binary.
4338 The resulting binaries can run on any Win32 system.
4340 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4342 <para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
4343 Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
4344 library; they have to do
4345 their input output using standard Haskell I/O libraries, or native Win32 bindings.
4349 <sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
4351 <para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
4352 <ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
4353 Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
4354 <command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
4355 A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
4357 <para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
4358 Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
4359 A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
4360 If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
4361 that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
4362 Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4363 does not change, but the implementation certainly does. Even the interfaces to functions
4364 it exports seem to change occasionally. So programs compiled by GHC might only run with
4365 particular versions of Cygwin. All of this seems very undesirable.
4368 Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
4369 we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
4370 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4374 <sect3><title>HOST_OS vs TARGET_OS</title>
4377 In the source code you'll find various ifdefs looking like:
4379 #ifdef mingw32_HOST_OS
4385 #ifdef mingw32_TARGET_OS
4389 These macros are set by the configure script (via the file config.h).
4390 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4393 The "host" system is the one on which GHC itself will be run.
4396 The "target" system is the one for which the program compiled by GHC will be run.
4399 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4400 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4405 <sect3><title>Summary</title>
4407 <para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
4408 how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
4409 by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
4411 <para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
4412 GHC-cygwin too is beyond our resources. The GHC we distribute
4413 therefore does not require Cygwin to run, nor do the programs it
4414 compiles require Cygwin.</para>
4416 <para>The instructions that follow describe how to build GHC-mingw. It is
4417 possible to build GHC-cygwin, but it's not a supported route, and the build system might
4420 <para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>. It
4421 uses the <Command>gcc</Command> that you specify using the
4422 <option>--with-gcc</option> flag when you run
4423 <Command>configure</Command> (see below).
4424 The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
4425 to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
4426 whatever one happens to be in your path. However, the makefiles do use whatever <Command>ld</Command>
4427 and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
4428 used to glom together .o files into a bigger .o file, or a .a file,
4429 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4430 Cygwin and Mingw use the same .o file format. So its ok.
4435 <Sect2><Title>Installing and configuring Cygwin</Title>
4437 <para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
4438 but you do need it to <emphasis>build</emphasis> GHC.</para>
4440 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4441 The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
4442 During the installation dialogue, make sure that you select:
4443 <command>cvs</command>, <command>openssh</command>,
4444 <command>autoconf</command>,
4445 <command>binutils</command> (includes ld and (I think) ar),
4446 <command>gcc</command>,
4447 <command>flex</command>,
4448 <command>make</command>.
4451 <para> Now set the following user environment variables:
4454 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4455 <constant>PATH</constant></para></listitem>
4459 Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
4460 don't do this you get very weird messages when you type
4461 <Command>make</Command>, such as:
4463 /c: /c: No such file or directory
4468 <listitem><para> Set <constant>SHELL</constant> to
4469 <Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
4470 <constant>SHELL</constant> is what you get.
4473 <listitem><para> Set <constant>HOME</constant> to point to your
4474 home directory. This is where, for example,
4475 <command>bash</command> will look for your <filename>.bashrc</filename>
4476 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4482 There are a few other things to do:
4486 By default, cygwin provides the command shell <filename>ash</filename>
4487 as <filename>sh.exe</filename>. We have often seen build-system problems that
4488 turn out to be due to bugs in <filename>ash</filename>
4490 and length of command lines). On the other hand <filename>bash</filename> seems
4492 So, in <filename>cygwin/bin</filename>
4493 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4494 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4495 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4496 you can't rename a running program!
4502 Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
4503 (and similarly for <Command>sh</Command>). Notice the hardwired path!
4504 So you need to ensure that your <Filename>/bin</Filename> directory has the following
4507 <listitem> <para><Command>sh</Command></para></listitem>
4508 <listitem> <para><Command>perl</Command></para></listitem>
4509 <listitem> <para><Command>cat</Command></para></listitem>
4511 All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
4512 installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
4513 <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
4514 (You can discover where your Cygwin
4515 root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
4516 Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
4517 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4518 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4524 <para>Finally, here are some things to be aware of when using Cygwin:
4526 <listitem> <para>Cygwin doesn't deal well with filenames that include
4527 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4531 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4532 magical text in it. So other programs that don't use Cygwin's
4533 I/O libraries won't recognise such files as symlinks.
4534 In particular, programs compiled by GHC are meant to be runnable
4535 without having Cygwin, so they don't use the Cygwin library, so
4536 they don't recognise symlinks.
4540 Win32 has a <command>find</command> command which is not the same as Cygwin's find.
4541 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4542 before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4543 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4544 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4551 <Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
4553 <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
4554 you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
4555 (not ssh) in the Cygwin list of applications!</para>
4557 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
4561 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
4562 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
4563 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
4564 and run it as follows:
4566 c:\tmp> set CYGWIN32=tty
4567 c:\tmp> c:/user/local/bin/ssh-keygen1
4572 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
4573 To determine your home directory <command>ssh</command> first looks in
4574 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
4575 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
4576 the setting of the environment variable $HOME</emphasis>. If the home directory is
4577 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
4579 ssh -v cvs.haskell.org
4581 which makes <command>ssh</command> print out information about its activity.
4583 <para> You can fix this problem, either by correcting the home-directory field in
4584 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
4585 you do that, <command>ssh</command> uses the $HOME environment variable instead.
4591 <para>To protect your
4592 <literal>.ssh</literal> from access by anyone else,
4593 right-click your <literal>.ssh</literal> directory, and
4594 select <literal>Properties</literal>. If you are not on
4595 the access control list, add yourself, and give yourself
4596 full permissions (the second panel). Remove everyone else
4597 from the access control list. Don't leave them there but
4598 deny them access, because 'they' may be a list that
4599 includes you!</para>
4603 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4604 you to have Unix permissions 600 (read/write for owner only)
4605 on the <literal>.ssh/identity</literal> file, else it
4606 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4607 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4608 The solution seems to be to set the $CYGWIN environment
4609 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4610 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4611 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4618 <Sect2><Title>Other things you need to install</Title>
4620 <para>You have to install the following other things to build GHC:
4624 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4625 This is what you will use to compile GHC. Add it in your
4626 <constant>PATH</constant>: the installer tells you the path element
4627 you need to add upon completion.
4633 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4634 Happy is a parser generator used to compile the Haskell grammar. Add it in your
4635 <constant>PATH</constant>.
4640 <para>Install Alex. This can be done by building from the
4641 source distribution in the usual way. Sources are
4642 available from <ulink
4643 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4647 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4648 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">).
4649 Just pick up a mingw bundle at
4650 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4651 We install it in <filename>c:/mingw</filename>.
4653 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4654 They are only going to get used by explicit access (via the --with-gcc flag you
4655 give to <Command>configure</Command> later). If you do add them to your path
4656 you are likely to get into a mess because their names overlap with Cygwin binaries.
4662 <para>We use <command>emacs</command> a lot, so we install that too.
4663 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4664 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4665 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4666 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4667 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4668 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4674 <para> Finally, check out a copy of GHC sources from
4675 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
4682 <Sect2><Title>Building GHC</Title>
4685 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
4686 the bullets below only tell
4687 you about Windows-specific wrinkles.</para>
4691 Run <Command>autoconf</Command> both in <filename>fptools</filename>
4692 and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
4693 get an error when you run <filename>./configure</filename>:
4696 creating mk/config.h
4697 mk/config.h is unchanged
4699 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4700 ./configure: ./configure: No such file or directory
4701 configure: error: ./configure failed for ghc
4706 <listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
4707 read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
4710 /usr/bin/autoconf: cannot create configure: permission denied
4712 Solution: delete <filename>configure</filename> first.
4717 You either need to add <filename>ghc</filename> to your
4718 <constant>PATH</constant> before you invoke
4719 <Command>configure</Command>, or use the <Command>configure</Command>
4720 option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
4725 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4726 This file occasionally remembers out-of-date configuration information, which
4727 can be really confusing.
4733 After <command>autoconf</command> run <command>./configure</command> in
4734 <filename>fptools/</filename> thus:
4737 ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
4739 This is the point at which you specify that you are building GHC-mingw
4740 (see <xref linkend="ghc-mingw">). </para>
4742 <para> Both these options are important! It's possible to get into
4743 trouble using the wrong C compiler!</para>
4745 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4746 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4747 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4748 understand a Cygwin path. For example, if you
4749 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4750 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4751 time it tries to invoke it. Worse, the failure comes with
4752 no error message whatsoever. GHC simply fails silently when first invoked,
4753 typically leaving you with this:
4755 make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4756 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4757 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4758 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4759 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4760 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4761 -optc-fomit-frame-pointer -O2 -static
4762 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4763 make[2]: *** [Adjustor.o] Error 1
4764 make[1]: *** [all] Error 1
4765 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4766 make: *** [all] Error 1
4772 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
4773 you'll have to do something more like:
4775 ./configure --with-gcc=...the Cygwin gcc...
4780 <listitem><para> You almost certainly want to set
4784 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
4785 This tells the build system not to split each library into a myriad of little object files, one
4786 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4787 it dramatically increases the time taken to build the libraries in the first place.
4791 <listitem><para> Do not attempt to build the documentation.
4792 It needs all kinds of wierd Jade stuff that we haven't worked out for
4793 Win32.</para></listitem>
projects / ghc-hetmet.git / blob