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),
1004 including native-code generator.</para>
1009 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
1010 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1012 <para>A registerised port is available for version 4.08,
1013 but GHC hasn't been built on that platform since (as far
1014 as we know). No native-code generator.</para>
1019 <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
1020 <indexterm><primary>i386-*-linux</primary></indexterm>
1022 <para>GHC works registerised and has a native code
1023 generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
1024 or later. NOTE about <literal>glibc</literal> versions:
1025 GHC binaries built on a system running <literal>glibc
1026 2.0</literal> won't work on a system running
1027 <literal>glibc 2.1</literal>, and vice versa. In general,
1028 don't expect compatibility between
1029 <literal>glibc</literal> versions, even if the shared
1030 library version hasn't changed.</para>
1035 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
1037 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1039 <para>GHC works registerised. Pre-built packages are
1040 available in the native package format, so if you just
1041 need binaries you're better off just installing the
1042 package (it might even be on your installation
1048 <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
1049 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1051 <para>Supported, with native code generator. Packages are
1052 available through the ports system in the native package
1058 <term>i386-unknown-netbsd (PCs running NetBSD and
1060 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1062 <para>Will require some minor porting effort, but should
1063 work registerised.</para>
1068 <term>i386-unknown-mingw32 (PCs running Windows)</term>
1069 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1071 <para>Fully supported under Win9x, WinNT, Win2k, and
1072 WinXP. Includes a native code generator. Building from
1073 source requires a recent <ulink
1074 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1075 to be installed.</para>
1080 <term>ia64-unknown-linux</term>
1081 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1083 <para>Supported, except there is no native code
1089 <term>x86_64-unknown-linux</term>
1090 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1092 <para>GHC currently works unregisterised. A registerised
1093 port is in progress.</para>
1098 <term>mips-sgi-irix5</term>
1099 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1101 <para>Port has worked in the past, but hasn't been tested
1102 for some time (and will certainly have rotted in various
1103 ways). As usual, we don't have access to machines and
1104 there hasn't been an overwhelming demand for this port,
1105 but feel free to get in touch.</para>
1110 <term>powerpc-ibm-aix</term>
1111 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1113 <para>Port currently doesn't work, needs some minimal
1114 porting effort. As usual, we don't have access to
1115 machines and there hasn't been an overwhelming demand for
1116 this port, but feel free to get in touch.</para>
1121 <term>powerpc-apple-darwin</term>
1122 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1124 <para>Supported registerised. Native code generator is
1125 almost working.</para>
1130 <term>powerpc-apple-linux</term>
1131 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1133 <para>Not supported (yet).</para>
1138 <para>Various other systems have had GHC ported to them in the
1139 distant past, including various Motorola 68k boxes. The 68k
1140 support still remains, but porting to one of these systems will
1141 certainly be a non-trivial task.</para>
1145 <title>What machines the other tools run on</title>
1147 <para>Unless you hear otherwise, the other tools work if GHC
1153 <sect1 id="sec-pre-supposed">
1154 <title>Installing pre-supposed utilities</title>
1156 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1157 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1159 <para>Here are the gory details about some utility programs you
1160 may need; <command>perl</command>, <command>gcc</command> and
1161 <command>happy</command> are the only important
1162 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1163 important if you're going for Parallel Haskell.) The
1164 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1165 script will tell you if you are missing something.</para>
1171 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1172 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1174 <para>GHC is required to build many of the tools, including
1175 GHC itself. If you need to port GHC to your platform
1176 because there isn't a binary distribution of GHC available,
1177 then see <xref linkend="sec-porting-ghc">.</para>
1179 <para>Which version of GHC you need will depend on the
1180 packages you intend to build. GHC itself will normally
1181 build using one of several older versions of itself - check
1182 the announcement or release notes for details.</para>
1188 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1189 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1191 <para><emphasis>You have to have Perl to proceed!</emphasis>
1192 Perl version 5 at least is required. GHC has been known to
1193 tickle bugs in Perl, so if you find that Perl crashes when
1194 running GHC try updating (or downgrading) your Perl
1195 installation. Versions of Perl that we use and are known to
1196 be fairly stable are 5.005 and 5.6.1.</para>
1198 <para>For Win32 platforms, you should use the binary
1199 supplied in the InstallShield (copy it to
1200 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1203 <para>Perl should be put somewhere so that it can be invoked
1204 by the <literal>#!</literal> script-invoking
1205 mechanism. The full pathname may need to be less than 32
1206 characters long on some systems.</para>
1211 <term>GNU C (<command>gcc</command>)</term>
1212 <indexterm><primary>pre-supposed: GCC (GNU C
1213 compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
1214 compiler), pre-supposed</primary></indexterm>
1216 <para>We recommend using GCC version 2.95.2 on all
1217 platforms. Failing that, version 2.7.2 is stable on most
1218 platforms. Earlier versions of GCC can be assumed not to
1219 work, and versions in between 2.7.2 and 2.95.2 (including
1220 <command>egcs</command>) have varying degrees of stability
1221 depending on the platform.</para>
1223 <para>GCC 3.2 is currently known to have problems building
1224 GHC on Sparc, but is stable on x86.</para>
1226 <para>If your GCC dies with “internal error” on
1227 some GHC source file, please let us know, so we can report
1228 it and get things improved. (Exception: on x86
1229 boxes—you may need to fiddle with GHC's
1230 <option>-monly-N-regs</option> option; see the User's
1236 <term>GNU Make</term>
1237 <indexterm><primary>make</primary><secondary>GNU</secondary>
1240 <para>The fptools build system makes heavy use of features
1241 specific to GNU <command>make</command>, so you must have
1242 this installed in order to build any of the fptools
1249 <indexterm><primary>Happy</primary></indexterm>
1251 <para>Happy is a parser generator tool for Haskell, and is
1252 used to generate GHC's parsers. Happy is written in
1253 Haskell, and is a project in the CVS repository
1254 (<literal>fptools/happy</literal>). It can be built from
1255 source, but bear in mind that you'll need GHC installed in
1256 order to build it. To avoid the chicken/egg problem,
1257 install a binary distribution of either Happy or GHC to get
1258 started. Happy distributions are available from <ulink
1259 url="http://www.haskell.org/happy/">Happy's Web
1260 Page</ulink>.</para>
1266 <indexterm><primary>Alex</primary></indexterm>
1268 <para>Alex is a lexical-analyser generator for Haskell,
1269 which GHC uses to generate its lexer. Like Happy, Alex is
1270 written in Haskell and is a project in the CVS repository.
1271 Alex distributions are available from <ulink
1272 url="http://www.haskell.org/alex/">Alex's Web
1273 Page</ulink>.</para>
1278 <term>Autoconf</term>
1279 <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
1280 <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
1282 <para>GNU Autoconf is needed if you intend to build from the
1283 CVS sources, it is <emphasis>not</emphasis> needed if you
1284 just intend to build a standard source distribution.</para>
1286 <para>Version 2.52 or later of autoconf is required.
1287 NB. vesrion 2.13 will no longer work, as of GHC version
1290 <para>Autoconf builds the <command>configure</command>
1291 script from <filename>configure.ac</filename> and
1292 <filename>aclocal.m4</filename>. If you modify either of
1293 these files, you'll need <command>autoconf</command> to
1294 rebuild <filename>configure</filename>.</para>
1299 <term><command>sed</command></term>
1300 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1301 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1303 <para>You need a working <command>sed</command> if you are
1304 going to build from sources. The build-configuration stuff
1305 needs it. GNU sed version 2.0.4 is no good! It has a bug
1306 in it that is tickled by the build-configuration. 2.0.5 is
1307 OK. Others are probably OK too (assuming we don't create too
1308 elaborate configure scripts.)</para>
1313 <para>One <literal>fptools</literal> project is worth a quick note
1314 at this point, because it is useful for all the others:
1315 <literal>glafp-utils</literal> contains several utilities which
1316 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1317 Like <command>lndir</command> for creating symbolic link
1320 <sect2 id="pre-supposed-gph-tools">
1321 <title>Tools for building parallel GHC (GPH)</title>
1325 <term>PVM version 3:</term>
1326 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1327 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1329 <para>PVM is the Parallel Virtual Machine on which
1330 Parallel Haskell programs run. (You only need this if you
1331 plan to run Parallel Haskell. Concurrent Haskell, which
1332 runs concurrent threads on a uniprocessor doesn't need
1333 it.) Underneath PVM, you can have (for example) a network
1334 of workstations (slow) or a multiprocessor box
1337 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1338 It is readily available on the net; I think I got it from
1339 <literal>research.att.com</literal>, in
1340 <filename>netlib</filename>.</para>
1342 <para>A PVM installation is slightly quirky, but easy to
1343 do. Just follow the <filename>Readme</filename>
1344 instructions.</para>
1349 <term><command>bash</command>:</term>
1350 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1352 <para>Sadly, the <command>gr2ps</command> script, used to
1353 convert “parallelism profiles” to PostScript,
1354 is written in Bash (GNU's Bourne Again shell). This bug
1355 will be fixed (someday).</para>
1361 <sect2 id="pre-supposed-other-tools">
1362 <title>Other useful tools</title>
1367 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1368 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1370 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1371 to build a couple of utilities in
1372 <literal>glafp-utils</literal>. Depending on your
1373 operating system, the supplied <command>lex</command> may
1374 or may not work; you should get the GNU version.</para>
1379 <para>More tools are required if you want to format the documentation
1380 that comes with GHC and other fptools projects. See <xref
1381 linkend="building-docs">.</para>
1385 <sect1 id="sec-building-from-source">
1386 <title>Building from source</title>
1388 <indexterm><primary>Building from source</primary></indexterm>
1389 <indexterm><primary>Source, building from</primary></indexterm>
1391 <para>You've been rash enough to want to build some of the Glasgow
1392 Functional Programming tools (GHC, Happy, nofib, etc.) from
1393 source. You've slurped the source, from the CVS repository or
1394 from a source distribution, and now you're sitting looking at a
1395 huge mound of bits, wondering what to do next.</para>
1397 <para>Gingerly, you type <command>make</command>. Wrong
1400 <para>This rest of this guide is intended for duffers like me, who
1401 aren't really interested in Makefiles and systems configurations,
1402 but who need a mental model of the interlocking pieces so that
1403 they can make them work, extend them consistently when adding new
1404 software, and lay hands on them gently when they don't
1407 <sect2 id="quick-start">
1408 <title>Quick Start</title>
1410 <para>If you are starting from a source distribution, and just
1411 want a completely standard build, then the following should
1414 <screen>$ ./configure
1419 <para>For GHC, this will do a 2-stage bootstrap build of the
1420 compiler, with profiling libraries, and install the
1423 <para>If you want to do anything at all non-standard, or you
1424 want to do some development, read on...</para>
1427 <sect2 id="sec-source-tree">
1428 <title>Your source tree</title>
1430 <para>The source code is held in your <emphasis>source
1431 tree</emphasis>. The root directory of your source tree
1432 <emphasis>must</emphasis> contain the following directories and
1437 <para><filename>Makefile</filename>: the root
1442 <para><filename>mk/</filename>: the directory that contains
1443 the main Makefile code, shared by all the
1444 <literal>fptools</literal> software.</para>
1448 <para><filename>configure.ac</filename>,
1449 <filename>config.sub</filename>,
1450 <filename>config.guess</filename>: these files support the
1451 configuration process.</para>
1455 <para><filename>install-sh</filename>.</para>
1459 <para>All the other directories are individual
1460 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1461 system—for example, the Glasgow Haskell Compiler
1462 (<literal>ghc</literal>), the Happy parser generator
1463 (<literal>happy</literal>), the <literal>nofib</literal>
1464 benchmark suite, and so on. You can have zero or more of these.
1465 Needless to say, some of them are needed to build others.</para>
1467 <para>The important thing to remember is that even if you want
1468 only one project (<literal>happy</literal>, say), you must have
1469 a source tree whose root directory contains
1470 <filename>Makefile</filename>, <filename>mk/</filename>,
1471 <filename>configure.ac</filename>, and the project(s) you want
1472 (<filename>happy/</filename> in this case). You cannot get by
1473 with just the <filename>happy/</filename> directory.</para>
1477 <title>Build trees</title>
1478 <indexterm><primary>build trees</primary></indexterm>
1479 <indexterm><primary>link trees, for building</primary></indexterm>
1481 <para>If you just want to build the software once on a single
1482 platform, then your source tree can also be your build tree, and
1483 you can skip the rest of this section.</para>
1485 <para>We often want to build multiple versions of our software
1486 for different architectures, or with different options
1487 (e.g. profiling). It's very desirable to share a single copy of
1488 the source code among all these builds.</para>
1490 <para>So for every source tree we have zero or more
1491 <emphasis>build trees</emphasis>. Each build tree is initially
1492 an exact copy of the source tree, except that each file is a
1493 symbolic link to the source file, rather than being a copy of
1494 the source file. There are “standard” Unix
1495 utilities that make such copies, so standard that they go by
1497 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1498 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1499 are two (If you don't have either, the source distribution
1500 includes sources for the X11
1501 <command>lndir</command>—check out
1502 <filename>fptools/glafp-utils/lndir</filename>). See <Xref
1503 LinkEnd="sec-storysofar"> for a typical invocation.</para>
1505 <para>The build tree does not need to be anywhere near the
1506 source tree in the file system. Indeed, one advantage of
1507 separating the build tree from the source is that the build tree
1508 can be placed in a non-backed-up partition, saving your systems
1509 support people from backing up untold megabytes of
1510 easily-regenerated, and rapidly-changing, gubbins. The golden
1511 rule is that (with a single exception—<XRef
1512 LinkEnd="sec-build-config">) <emphasis>absolutely everything in
1513 the build tree is either a symbolic link to the source tree, or
1514 else is mechanically generated</emphasis>. It should be
1515 perfectly OK for your build tree to vanish overnight; an hour or
1516 two compiling and you're on the road again.</para>
1518 <para>You need to be a bit careful, though, that any new files
1519 you create (if you do any development work) are in the source
1520 tree, not a build tree!</para>
1522 <para>Remember, that the source files in the build tree are
1523 <emphasis>symbolic links</emphasis> to the files in the source
1524 tree. (The build tree soon accumulates lots of built files like
1525 <filename>Foo.o</filename>, as well.) You can
1526 <emphasis>delete</emphasis> a source file from the build tree
1527 without affecting the source tree (though it's an odd thing to
1528 do). On the other hand, if you <emphasis>edit</emphasis> a
1529 source file from the build tree, you'll edit the source-tree
1530 file directly. (You can set up Emacs so that if you edit a
1531 source file from the build tree, Emacs will silently create an
1532 edited copy of the source file in the build tree, leaving the
1533 source file unchanged; but the danger is that you think you've
1534 edited the source file whereas actually all you've done is edit
1535 the build-tree copy. More commonly you do want to edit the
1536 source file.)</para>
1538 <para>Like the source tree, the top level of your build tree
1539 must be (a linked copy of) the root directory of the
1540 <literal>fptools</literal> suite. Inside Makefiles, the root of
1541 your build tree is called
1542 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1543 In the rest of this document path names are relative to
1544 <constant>$(FPTOOLS_TOP)</constant> unless
1545 otherwise stated. For example, the file
1546 <filename>ghc/mk/target.mk</filename> is actually
1547 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
1550 <sect2 id="sec-build-config">
1551 <title>Getting the build you want</title>
1553 <para>When you build <literal>fptools</literal> you will be
1554 compiling code on a particular <emphasis>host
1555 platform</emphasis>, to run on a particular <emphasis>target
1556 platform</emphasis> (usually the same as the host
1557 platform)<indexterm><primary>platform</primary></indexterm>.
1558 The difficulty is that there are minor differences between
1559 different platforms; minor, but enough that the code needs to be
1560 a bit different for each. There are some big differences too:
1561 for a different architecture we need to build GHC with a
1562 different native-code generator.</para>
1564 <para>There are also knobs you can turn to control how the
1565 <literal>fptools</literal> software is built. For example, you
1566 might want to build GHC optimised (so that it runs fast) or
1567 unoptimised (so that you can compile it fast after you've
1568 modified it. Or, you might want to compile it with debugging on
1569 (so that extra consistency-checking code gets included) or off.
1572 <para>All of this stuff is called the
1573 <emphasis>configuration</emphasis> of your build. You set the
1574 configuration using a three-step process.</para>
1578 <term>Step 1: get ready for configuration.</term>
1580 <para>NOTE: if you're starting from a source distribution,
1581 rather than CVS sources, you can skip this step.</para>
1583 <para>Change directory to
1584 <constant>$(FPTOOLS_TOP)</constant> and
1586 <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
1587 (with no arguments). This GNU program converts
1588 <filename><constant>$(FPTOOLS_TOP)</constant>/configure.ac</filename>
1589 to a shell script called
1590 <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
1593 <para>Some projects, including GHC, have their own
1594 configure script. If there's an
1595 <constant>$(FPTOOLS_TOP)/<project>/configure.ac</constant>,
1596 then you need to run <command>autoconf</command> in that
1597 directory too.</para>
1599 <para>Both these steps are completely
1600 platform-independent; they just mean that the
1601 human-written file (<filename>configure.ac</filename>) can
1602 be short, although the resulting shell script,
1603 <command>configure</command>, and
1604 <filename>mk/config.h.in</filename>, are long.</para>
1609 <term>Step 2: system configuration.</term>
1611 <para>Runs the newly-created <command>configure</command>
1612 script, thus:</para>
1615 ./configure <optional><parameter>args</parameter></optional>
1618 <para><command>configure</command>'s mission is to scurry
1619 round your computer working out what architecture it has,
1620 what operating system, whether it has the
1621 <Function>vfork</Function> system call, where
1622 <command>tar</command> is kept, whether
1623 <command>gcc</command> is available, where various obscure
1624 <literal>#include</literal> files are, whether it's a
1625 leap year, and what the systems manager had for lunch. It
1626 communicates these snippets of information in two
1633 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1635 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1636 substituting for things between
1637 “<literal>@</literal>” brackets. So,
1638 “<literal>@HaveGcc@</literal>” will be
1639 replaced by “<literal>YES</literal>” or
1640 “<literal>NO</literal>” depending on what
1641 <command>configure</command> finds.
1642 <filename>mk/config.mk</filename> is included by every
1643 Makefile (directly or indirectly), so the
1644 configuration information is thereby communicated to
1645 all Makefiles.</para>
1649 <para> It translates
1650 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1652 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1653 The latter is <literal>#include</literal>d by
1654 various C programs, which can thereby make use of
1655 configuration information.</para>
1659 <para><command>configure</command> takes some optional
1660 arguments. Use <literal>./configure --help</literal> to
1661 get a list of the available arguments. Here are some of
1662 the ones you might need:</para>
1666 <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
1667 <indexterm><primary><literal>--with-ghc</literal></primary>
1670 <para>Specifies the path to an installed GHC which
1671 you would like to use. This compiler will be used
1672 for compiling GHC-specific code (eg. GHC itself).
1673 This option <emphasis>cannot</emphasis> be specified
1674 using <filename>build.mk</filename> (see later),
1675 because <command>configure</command> needs to
1676 auto-detect the version of GHC you're using. The
1677 default is to look for a compiler named
1678 <literal>ghc</literal> in your path.</para>
1683 <term><literal>--with-hc=<parameter>path</parameter></literal></term>
1684 <indexterm><primary><literal>--with-hc</literal></primary>
1687 <para>Specifies the path to any installed Haskell
1688 compiler. This compiler will be used for compiling
1689 generic Haskell code. The default is to use
1690 <literal>ghc</literal>.</para>
1695 <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
1696 <indexterm><primary><literal>--with-gcc</literal></primary>
1699 <para>Specifies the path to the installed GCC. This
1700 compiler will be used to compile all C files,
1701 <emphasis>except</emphasis> any generated by the
1702 installed Haskell compiler, which will have its own
1703 idea of which C compiler (if any) to use. The
1704 default is to use <literal>gcc</literal>.</para>
1709 <para><command>configure</command> caches the results of
1710 its run in <filename>config.cache</filename>. Quite often
1711 you don't want that; you're running
1712 <command>configure</command> a second time because
1713 something has changed. In that case, simply delete
1714 <filename>config.cache</filename>.</para>
1719 <term>Step 3: build configuration.</term>
1721 <para>Next, you say how this build of
1722 <literal>fptools</literal> is to differ from the standard
1723 defaults by creating a new file
1724 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1725 <emphasis>in the build tree</emphasis>. This file is the
1726 one and only file you edit in the build tree, precisely
1727 because it says how this build differs from the source.
1728 (Just in case your build tree does die, you might want to
1729 keep a private directory of <filename>build.mk</filename>
1730 files, and use a symbolic link in each build tree to point
1731 to the appropriate one.) So
1732 <filename>mk/build.mk</filename> never exists in the
1733 source tree—you create one in each build tree from
1734 the template. We'll discuss what to put in it
1740 <para>And that's it for configuration. Simple, eh?</para>
1742 <para>What do you put in your build-specific configuration file
1743 <filename>mk/build.mk</filename>? <emphasis>For almost all
1744 purposes all you will do is put make variable definitions that
1745 override those in</emphasis>
1746 <filename>mk/config.mk.in</filename>. The whole point of
1747 <filename>mk/config.mk.in</filename>—and its derived
1748 counterpart <filename>mk/config.mk</filename>—is to define
1749 the build configuration. It is heavily commented, as you will
1750 see if you look at it. So generally, what you do is look at
1751 <filename>mk/config.mk.in</filename>, and add definitions in
1752 <filename>mk/build.mk</filename> that override any of the
1753 <filename>config.mk</filename> definitions that you want to
1754 change. (The override occurs because the main boilerplate file,
1755 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1756 includes <filename>build.mk</filename> after
1757 <filename>config.mk</filename>.)</para>
1759 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1760 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1762 <para>For example, <filename>config.mk.in</filename> contains
1763 the definition:</para>
1766 GhcHcOpts=-O -Rghc-timing
1769 <para>The accompanying comment explains that this is the list of
1770 flags passed to GHC when building GHC itself. For doing
1771 development, it is wise to add <literal>-DDEBUG</literal>, to
1772 enable debugging code. So you would add the following to
1773 <filename>build.mk</filename>:</para>
1775 <para>or, if you prefer,</para>
1778 GhcHcOpts += -DDEBUG
1781 <para>GNU <command>make</command> allows existing definitions to
1782 have new text appended using the “<literal>+=</literal>”
1783 operator, which is quite a convenient feature.)</para>
1785 <para>If you want to remove the <literal>-O</literal> as well (a
1786 good idea when developing, because the turn-around cycle gets a
1787 lot quicker), you can just override
1788 <literal>GhcLibHcOpts</literal> altogether:</para>
1791 GhcHcOpts=-DDEBUG -Rghc-timing
1794 <para>When reading <filename>config.mk.in</filename>, remember
1795 that anything between “@...@” signs is going to be substituted
1796 by <command>configure</command> later. You
1797 <emphasis>can</emphasis> override the resulting definition if
1798 you want, but you need to be a bit surer what you are doing.
1799 For example, there's a line that says:</para>
1805 <para>This defines the Make variables <constant>TAR</constant>
1806 to the pathname for a <command>tar</command> that
1807 <command>configure</command> finds somewhere. If you have your
1808 own pet <command>tar</command> you want to use instead, that's
1809 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1815 <para>You do not <emphasis>have</emphasis> to have a
1816 <filename>mk/build.mk</filename> file at all; if you don't,
1817 you'll get all the default settings from
1818 <filename>mk/config.mk.in</filename>.</para>
1820 <para>You can also use <filename>build.mk</filename> to override
1821 anything that <command>configure</command> got wrong. One place
1822 where this happens often is with the definition of
1823 <constant>FPTOOLS_TOP_ABS</constant>: this
1824 variable is supposed to be the canonical path to the top of your
1825 source tree, but if your system uses an automounter then the
1826 correct directory is hard to find automatically. If you find
1827 that <command>configure</command> has got it wrong, just put the
1828 correct definition in <filename>build.mk</filename>.</para>
1832 <sect2 id="sec-storysofar">
1833 <title>The story so far</title>
1835 <para>Let's summarise the steps you need to carry to get
1836 yourself a fully-configured build tree from scratch.</para>
1840 <para> Get your source tree from somewhere (CVS repository
1841 or source distribution). Say you call the root directory
1842 <filename>myfptools</filename> (it does not have to be
1843 called <filename>fptools</filename>). Make sure that you
1844 have the essential files (see <XRef
1845 LinkEnd="sec-source-tree">).</para>
1850 <para>(Optional) Use <command>lndir</command> or
1851 <command>mkshadowdir</command> to create a build tree.</para>
1855 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1858 <para>(N.B. <command>mkshadowdir</command>'s first argument
1859 is taken relative to its second.) You probably want to give
1860 the build tree a name that suggests its main defining
1861 characteristic (in your mind at least), in case you later
1866 <para>Change directory to the build tree. Everything is
1867 going to happen there now.</para>
1870 $ cd /scratch/joe-bloggs/myfptools-sun4
1876 <para>Prepare for system configuration:</para>
1882 <para>(You can skip this step if you are starting from a
1883 source distribution, and you already have
1884 <filename>configure</filename> and
1885 <filename>mk/config.h.in</filename>.)</para>
1887 <para>Some projects, including GHC itself, have their own
1888 configure scripts, so it is necessary to run autoconf again
1889 in the appropriate subdirectories. eg:</para>
1892 $ (cd ghc; autoconf)
1897 <para>Do system configuration:</para>
1903 <para>Don't forget to check whether you need to add any
1904 arguments to <literal>configure</literal>; for example, a
1905 common requirement is to specify which GHC to use with
1906 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1910 <para>Create the file <filename>mk/build.mk</filename>,
1911 adding definitions for your desired configuration
1920 <para>You can make subsequent changes to
1921 <filename>mk/build.mk</filename> as often as you like. You do
1922 not have to run any further configuration programs to make these
1923 changes take effect. In theory you should, however, say
1924 <command>gmake clean</command>, <command>gmake all</command>,
1925 because configuration option changes could affect
1926 anything—but in practice you are likely to know what's
1931 <title>Making things</title>
1933 <para>At this point you have made yourself a fully-configured
1934 build tree, so you are ready to start building real
1937 <para>The first thing you need to know is that <emphasis>you
1938 must use GNU <command>make</command>, usually called
1939 <command>gmake</command>, not standard Unix
1940 <command>make</command></emphasis>. If you use standard Unix
1941 <command>make</command> you will get all sorts of error messages
1942 (but no damage) because the <literal>fptools</literal>
1943 <command>Makefiles</command> use GNU <command>make</command>'s
1944 facilities extensively.</para>
1946 <para>To just build the whole thing, <command>cd</command> to
1947 the top of your <literal>fptools</literal> tree and type
1948 <command>gmake</command>. This will prepare the tree and build
1949 the various projects in the correct order.</para>
1952 <sect2 id="sec-bootstrapping">
1953 <title>Bootstrapping GHC</title>
1955 <para>GHC requires a 2-stage bootstrap in order to provide
1956 full functionality, including GHCi. By a 2-stage bootstrap, we
1957 mean that the compiler is built once using the installed GHC,
1958 and then again using the compiler built in the first stage. You
1959 can also build a stage 3 compiler, but this normally isn't
1960 necessary except to verify that the stage 2 compiler is working
1963 <para>Note that when doing a bootstrap, the stage 1 compiler
1964 must be built, followed by the runtime system and libraries, and
1965 then the stage 2 compiler. The correct ordering is implemented
1966 by the top-level fptools <filename>Makefile</filename>, so if
1967 you want everything to work automatically it's best to start
1968 <command>make</command> from the top of the tree. When building
1969 GHC, the top-level fptools <filename>Makefile</filename> is set
1970 up to do a 2-stage bootstrap by default (when you say
1971 <command>make</command>). Some other targets it supports
1978 <para>Build everything as normal, including the stage 1
1986 <para>Build the stage 2 compiler only.</para>
1993 <para>Build the stage 3 compiler only.</para>
1998 <term>bootstrap</term> <term>bootstrap2</term>
2000 <para>Build stage 1 followed by stage 2.</para>
2005 <term>bootstrap3</term>
2007 <para>Build stages 1, 2 and 3.</para>
2012 <term>install</term>
2014 <para>Install everything, including the compiler built in
2015 stage 2. To override the stage, say <literal>make install
2016 stage=<replaceable>n</replaceable></literal> where
2017 <replaceable>n</replaceable> is the stage to install.</para>
2022 <para>The top-level <filename>Makefile</filename> also arranges
2023 to do the appropriate <literal>make boot</literal> steps (see
2024 below) before actually building anything.</para>
2026 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2027 and <literal>stage3</literal> targets also work in the
2028 <literal>ghc/compiler</literal> directory, but don't forget that
2029 each stage requires its own <literal>make boot</literal> step:
2030 for example, you must do</para>
2032 <screen>$ make boot stage=2</screen>
2034 <para>before <literal>make stage2</literal> in
2035 <literal>ghc/compiler</literal>.</para>
2038 <sect2 id="sec-standard-targets">
2039 <title>Standard Targets</title>
2040 <indexterm><primary>targets, standard makefile</primary></indexterm>
2041 <indexterm><primary>makefile targets</primary></indexterm>
2043 <para>In any directory you should be able to make the following:</para>
2047 <term><literal>boot</literal></term>
2049 <para>does the one-off preparation required to get ready
2050 for the real work. Notably, it does <command>gmake
2051 depend</command> in all directories that contain programs.
2052 It also builds the necessary tools for compilation to
2055 <para>Invoking the <literal>boot</literal> target
2056 explicitly is not normally necessary. From the top-level
2057 <literal>fptools</literal> directory, invoking
2058 <literal>gmake</literal> causes <literal>gmake boot
2059 all</literal> to be invoked in each of the project
2060 subdirectories, in the order specified by
2061 <literal>$(AllTargets)</literal> in
2062 <literal>config.mk</literal>.</para>
2064 <para>If you're working in a subdirectory somewhere and
2065 need to update the dependencies, <literal>gmake
2066 boot</literal> is a good way to do it.</para>
2071 <term><literal>all</literal></term>
2073 <para>makes all the final target(s) for this Makefile.
2074 Depending on which directory you are in a “final
2075 target” may be an executable program, a library
2076 archive, a shell script, or a Postscript file. Typing
2077 <command>gmake</command> alone is generally the same as
2078 typing <command>gmake all</command>.</para>
2083 <term><literal>install</literal></term>
2085 <para>installs the things built by <literal>all</literal>
2086 (except for the documentation). Where does it install
2087 them? That is specified by
2088 <filename>mk/config.mk.in</filename>; you can override it
2089 in <filename>mk/build.mk</filename>, or by running
2090 <command>configure</command> with command-line arguments
2091 like <literal>--bindir=/home/simonpj/bin</literal>; see
2092 <literal>./configure --help</literal> for the full
2098 <term><literal>install-docs</literal></term>
2100 <para>installs the documentation. Otherwise behaves just
2101 like <literal>install</literal>.</para>
2106 <term><literal>uninstall</literal></term>
2108 <para>reverses the effect of
2109 <literal>install</literal>.</para>
2114 <term><literal>clean</literal></term>
2116 <para>Delete all files from the current directory that are
2117 normally created by building the program. Don't delete
2118 the files that record the configuration, or files
2119 generated by <command>gmake boot</command>. Also preserve
2120 files that could be made by building, but normally aren't
2121 because the distribution comes with them.</para>
2126 <term><literal>distclean</literal></term>
2128 <para>Delete all files from the current directory that are
2129 created by configuring or building the program. If you
2130 have unpacked the source and built the program without
2131 creating any other files, <literal>make
2132 distclean</literal> should leave only the files that were
2133 in the distribution.</para>
2138 <term><literal>mostlyclean</literal></term>
2140 <para>Like <literal>clean</literal>, but may refrain from
2141 deleting a few files that people normally don't want to
2147 <term><literal>maintainer-clean</literal></term>
2149 <para>Delete everything from the current directory that
2150 can be reconstructed with this Makefile. This typically
2151 includes everything deleted by
2152 <literal>distclean</literal>, plus more: C source files
2153 produced by Bison, tags tables, Info files, and so
2156 <para>One exception, however: <literal>make
2157 maintainer-clean</literal> should not delete
2158 <filename>configure</filename> even if
2159 <filename>configure</filename> can be remade using a rule
2160 in the <filename>Makefile</filename>. More generally,
2161 <literal>make maintainer-clean</literal> should not delete
2162 anything that needs to exist in order to run
2163 <filename>configure</filename> and then begin to build the
2169 <term><literal>check</literal></term>
2171 <para>run the test suite.</para>
2176 <para>All of these standard targets automatically recurse into
2177 sub-directories. Certain other standard targets do not:</para>
2181 <term><literal>configure</literal></term>
2183 <para>is only available in the root directory
2184 <constant>$(FPTOOLS_TOP)</constant>; it has
2185 been discussed in <XRef
2186 LinkEnd="sec-build-config">.</para>
2191 <term><literal>depend</literal></term>
2193 <para>make a <filename>.depend</filename> file in each
2194 directory that needs it. This <filename>.depend</filename>
2195 file contains mechanically-generated dependency
2196 information; for example, suppose a directory contains a
2197 Haskell source module <filename>Foo.lhs</filename> which
2198 imports another module <literal>Baz</literal>. Then the
2199 generated <filename>.depend</filename> file will contain
2200 the dependency:</para>
2206 <para>which says that the object file
2207 <filename>Foo.o</filename> depends on the interface file
2208 <filename>Baz.hi</filename> generated by compiling module
2209 <literal>Baz</literal>. The <filename>.depend</filename>
2210 file is automatically included by every Makefile.</para>
2215 <term><literal>binary-dist</literal></term>
2217 <para>make a binary distribution. This is the target we
2218 use to build the binary distributions of GHC and
2224 <term><literal>dist</literal></term>
2226 <para>make a source distribution. Note that this target
2227 does “make distclean” as part of its work;
2228 don't use it if you want to keep what you've built.</para>
2233 <para>Most <filename>Makefile</filename>s have targets other
2234 than these. You can discover them by looking in the
2235 <filename>Makefile</filename> itself.</para>
2239 <title>Using a project from the build tree</title>
2241 <para>If you want to build GHC (say) and just use it direct from
2242 the build tree without doing <literal>make install</literal>
2243 first, you can run the in-place driver script:
2244 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2246 <para> Do <emphasis>NOT</emphasis> use
2247 <filename>ghc/compiler/ghc</filename>, or
2248 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2249 scripts intended for installation, and contain hard-wired paths
2250 to the installed libraries, rather than the libraries in the
2253 <para>Happy can similarly be run from the build tree, using
2254 <filename>happy/src/happy-inplace</filename>, and similarly for
2255 Alex and Haddock.</para>
2259 <title>Fast Making</title>
2261 <indexterm><primary>fastmake</primary></indexterm>
2262 <indexterm><primary>dependencies, omitting</primary></indexterm>
2263 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2265 <para>Sometimes the dependencies get in the way: if you've made
2266 a small change to one file, and you're absolutely sure that it
2267 won't affect anything else, but you know that
2268 <command>make</command> is going to rebuild everything anyway,
2269 the following hack may be useful:</para>
2275 <para>This tells the make system to ignore dependencies and just
2276 build what you tell it to. In other words, it's equivalent to
2277 temporarily removing the <filename>.depend</filename> file in
2278 the current directory (where <command>mkdependHS</command> and
2279 friends store their dependency information).</para>
2281 <para>A bit of history: GHC used to come with a
2282 <command>fastmake</command> script that did the above job, but
2283 GNU make provides the features we need to do it without
2284 resorting to a script. Also, we've found that fastmaking is
2285 less useful since the advent of GHC's recompilation checker (see
2286 the User's Guide section on "Separate Compilation").</para>
2290 <sect1 id="sec-makefile-arch">
2291 <title>The <filename>Makefile</filename> architecture</title>
2292 <indexterm><primary>makefile architecture</primary></indexterm>
2294 <para><command>make</command> is great if everything
2295 works—you type <command>gmake install</command> and lo! the
2296 right things get compiled and installed in the right places. Our
2297 goal is to make this happen often, but somehow it often doesn't;
2298 instead some weird error message eventually emerges from the
2299 bowels of a directory you didn't know existed.</para>
2301 <para>The purpose of this section is to give you a road-map to
2302 help you figure out what is going right and what is going
2306 <title>Debugging</title>
2308 <para>Debugging <filename>Makefile</filename>s is something of a
2309 black art, but here's a couple of tricks that we find
2310 particularly useful. The following command allows you to see
2311 the contents of any make variable in the context of the current
2312 <filename>Makefile</filename>:</para>
2314 <screen>$ make show VALUE=HS_SRCS</screen>
2316 <para>where you can replace <literal>HS_SRCS</literal> with the
2317 name of any variable you wish to see the value of.</para>
2319 <para>GNU make has a <option>-d</option> option which generates
2320 a dump of the decision procedure used to arrive at a conclusion
2321 about which files should be recompiled. Sometimes useful for
2322 tracking down problems with superfluous or missing
2323 recompilations.</para>
2327 <title>A small project</title>
2329 <para>To get started, let us look at the
2330 <filename>Makefile</filename> for an imaginary small
2331 <literal>fptools</literal> project, <literal>small</literal>.
2332 Each project in <literal>fptools</literal> has its own directory
2333 in <constant>FPTOOLS_TOP</constant>, so the
2334 <literal>small</literal> project will have its own directory
2335 <constant>FPOOLS_TOP/small/</constant>. Inside the
2336 <filename>small/</filename> directory there will be a
2337 <filename>Makefile</filename>, looking something like
2340 <indexterm><primary>Makefile, minimal</primary></indexterm>
2343 # Makefile for fptools project "small"
2346 include $(TOP)/mk/boilerplate.mk
2348 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2351 include $(TOP)/target.mk
2354 <para>this <filename>Makefile</filename> has three
2359 <para>The first section includes
2362 One of the most important
2363 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2364 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2369 a file of “boilerplate” code from the level
2370 above (which in this case will be
2371 <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2372 As its name suggests, <filename>boilerplate.mk</filename>
2373 consists of a large quantity of standard
2374 <filename>Makefile</filename> code. We discuss this
2375 boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
2376 <indexterm><primary>include, directive in
2377 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2378 inclusion</primary></indexterm></para>
2380 <para>Before the <literal>include</literal> statement, you
2381 must define the <command>make</command> variable
2382 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2383 to be the directory containing the <filename>mk</filename>
2384 directory in which the <filename>boilerplate.mk</filename>
2385 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2388 include ../mk/boilerplate.mk # NO NO NO
2392 <para>Why? Because the <filename>boilerplate.mk</filename>
2393 file needs to know where it is, so that it can, in turn,
2394 <literal>include</literal> other files. (Unfortunately,
2395 when an <literal>include</literal>d file does an
2396 <literal>include</literal>, the filename is treated relative
2397 to the directory in which <command>gmake</command> is being
2398 run, not the directory in which the
2399 <literal>include</literal>d sits.) In general,
2400 <emphasis>every file <filename>foo.mk</filename> assumes
2402 <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
2403 refers to itself.</emphasis> It is up to the
2404 <filename>Makefile</filename> doing the
2405 <literal>include</literal> to ensure this is the case.</para>
2407 <para>Files intended for inclusion in other
2408 <filename>Makefile</filename>s are written to have the
2409 following property: <emphasis>after
2410 <filename>foo.mk</filename> is <literal>include</literal>d,
2411 it leaves <constant>TOP</constant> containing the same value
2412 as it had just before the <literal>include</literal>
2413 statement</emphasis>. In our example, this invariant
2414 guarantees that the <literal>include</literal> for
2415 <filename>target.mk</filename> will look in the same
2416 directory as that for <filename>boilerplate.mk</filename>.</para>
2420 <para> The second section defines the following standard
2421 <command>make</command> variables:
2422 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2423 (the source files from which is to be built), and
2424 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2425 (the executable binary to be built). We will discuss in
2426 more detail what the “standard variables” are,
2427 and how they affect what happens, in <XRef
2428 LinkEnd="sec-targets">.</para>
2430 <para>The definition for <constant>SRCS</constant> uses the
2431 useful GNU <command>make</command> construct
2432 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2433 which expands to a list of all the files matching the
2434 pattern <literal>pat</literal> in the current directory. In
2435 this example, <constant>SRCS</constant> is set to the list
2436 of all the <filename>.lhs</filename> and
2437 <filename>.c</filename> files in the directory. (Let's
2438 suppose there is one of each, <filename>Foo.lhs</filename>
2439 and <filename>Baz.c</filename>.)</para>
2443 <para>The last section includes a second file of standard
2445 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2446 It contains the rules that tell <command>gmake</command> how
2447 to make the standard targets (<Xref
2448 LinkEnd="sec-standard-targets">). Why, you ask, can't this
2449 standard code be part of
2450 <filename>boilerplate.mk</filename>? Good question. We
2451 discuss the reason later, in <Xref
2452 LinkEnd="sec-boiler-arch">.</para>
2454 <para>You do not <emphasis>have</emphasis> to
2455 <literal>include</literal> the
2456 <filename>target.mk</filename> file. Instead, you can write
2457 rules of your own for all the standard targets. Usually,
2458 though, you will find quite a big payoff from using the
2459 canned rules in <filename>target.mk</filename>; the price
2460 tag is that you have to understand what canned rules get
2461 enabled, and what they do (<Xref
2462 LinkEnd="sec-targets">).</para>
2466 <para>In our example <filename>Makefile</filename>, most of the
2467 work is done by the two <literal>include</literal>d files. When
2468 you say <command>gmake all</command>, the following things
2473 <para><command>gmake</command> figures out that the object
2474 files are <filename>Foo.o</filename> and
2475 <filename>Baz.o</filename>.</para>
2479 <para>It uses a boilerplate pattern rule to compile
2480 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2481 using a Haskell compiler. (Which one? That is set in the
2482 build configuration.)</para>
2486 <para>It uses another standard pattern rule to compile
2487 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2488 using a C compiler. (Ditto.)</para>
2492 <para>It links the resulting <filename>.o</filename> files
2493 together to make <literal>small</literal>, using the Haskell
2494 compiler to do the link step. (Why not use
2495 <command>ld</command>? Because the Haskell compiler knows
2496 what standard libraries to link in. How did
2497 <command>gmake</command> know to use the Haskell compiler to
2498 do the link, rather than the C compiler? Because we set the
2499 variable <constant>HS_PROG</constant> rather than
2500 <constant>C_PROG</constant>.)</para>
2504 <para>All <filename>Makefile</filename>s should follow the above
2505 three-section format.</para>
2509 <title>A larger project</title>
2511 <para>Larger projects are usually structured into a number of
2512 sub-directories, each of which has its own
2513 <filename>Makefile</filename>. (In very large projects, this
2514 sub-structure might be iterated recursively, though that is
2515 rare.) To give you the idea, here's part of the directory
2516 structure for the (rather large) GHC project:</para>
2526 ...source files for documentation...
2529 ...source files for driver...
2532 parser/...source files for parser...
2533 renamer/...source files for renamer...
2537 <para>The sub-directories <filename>docs</filename>,
2538 <filename>driver</filename>, <filename>compiler</filename>, and
2539 so on, each contains a sub-component of GHC, and each has its
2540 own <filename>Makefile</filename>. There must also be a
2541 <filename>Makefile</filename> in
2542 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
2543 It does most of its work by recursively invoking
2544 <command>gmake</command> on the <filename>Makefile</filename>s
2545 in the sub-directories. We say that
2546 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2547 <filename>Makefile</filename></emphasis>, because it does little
2548 except organise its children, while the
2549 <filename>Makefile</filename>s in the sub-directories are all
2550 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2551 principle the sub-directories might themselves contain a
2552 non-leaf <filename>Makefile</filename> and several
2553 sub-sub-directories, but that does not happen in GHC.)</para>
2555 <para>The <filename>Makefile</filename> in
2556 <filename>ghc/compiler</filename> is considered a leaf
2557 <filename>Makefile</filename> even though the
2558 <filename>ghc/compiler</filename> has sub-directories, because
2559 these sub-directories do not themselves have
2560 <filename>Makefile</filename>s in them. They are just used to
2561 structure the collection of modules that make up GHC, but all
2562 are managed by the single <filename>Makefile</filename> in
2563 <filename>ghc/compiler</filename>.</para>
2565 <para>You will notice that <filename>ghc/</filename> also
2566 contains a directory <filename>ghc/mk/</filename>. It contains
2567 GHC-specific <filename>Makefile</filename> boilerplate code.
2568 More precisely:</para>
2572 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2573 at the top of <filename>ghc/Makefile</filename>, and of all
2574 the leaf <filename>Makefile</filename>s in the
2575 sub-directories. It in turn <literal>include</literal>s the
2576 main boilerplate file
2577 <filename>mk/boilerplate.mk</filename>.</para>
2581 <para><filename>ghc/mk/target.mk</filename> is
2582 <literal>include</literal>d at the bottom of
2583 <filename>ghc/Makefile</filename>, and of all the leaf
2584 <filename>Makefile</filename>s in the sub-directories. It
2585 in turn <literal>include</literal>s the file
2586 <filename>mk/target.mk</filename>.</para>
2590 <para>So these two files are the place to look for GHC-wide
2591 customisation of the standard boilerplate.</para>
2594 <sect2 id="sec-boiler-arch">
2595 <title>Boilerplate architecture</title>
2596 <indexterm><primary>boilerplate architecture</primary></indexterm>
2598 <para>Every <filename>Makefile</filename> includes a
2599 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2600 file at the top, and
2601 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2602 file at the bottom. In this section we discuss what is in these
2603 files, and why there have to be two of them. In general:</para>
2607 <para><filename>boilerplate.mk</filename> consists of:</para>
2611 <para><emphasis>Definitions of millions of
2612 <command>make</command> variables</emphasis> that
2613 collectively specify the build configuration. Examples:
2614 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2615 the options to feed to the Haskell compiler;
2616 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2617 the sub-directories to enable within the
2618 <literal>nofib</literal> project;
2619 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2620 the name of the Haskell compiler to use when compiling
2621 GHC in the <literal>ghc</literal> project.</para>
2625 <para><emphasis>Standard pattern rules</emphasis> that
2626 tell <command>gmake</command> how to construct one file
2627 from another.</para>
2631 <para><filename>boilerplate.mk</filename> needs to be
2632 <literal>include</literal>d at the <emphasis>top</emphasis>
2633 of each <filename>Makefile</filename>, so that the user can
2634 replace the boilerplate definitions or pattern rules by
2635 simply giving a new definition or pattern rule in the
2636 <filename>Makefile</filename>. <command>gmake</command>
2637 simply takes the last definition as the definitive one.</para>
2639 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2640 definitions, it is also quite common to
2641 <emphasis>augment</emphasis> them. For example, a
2642 <filename>Makefile</filename> might say:</para>
2648 <para>thereby adding “<option>-O</option>” to
2650 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2654 <para><filename>target.mk</filename> contains
2655 <command>make</command> rules for the standard targets
2656 described in <Xref LinkEnd="sec-standard-targets">. These
2657 rules are selectively included, depending on the setting of
2658 certain <command>make</command> variables. These variables
2659 are usually set in the middle section of the
2660 <filename>Makefile</filename> between the two
2661 <literal>include</literal>s.</para>
2663 <para><filename>target.mk</filename> must be included at the
2664 end (rather than being part of
2665 <filename>boilerplate.mk</filename>) for several tiresome
2671 <para><command>gmake</command> commits target and
2672 dependency lists earlier than it should. For example,
2673 <FIlename>target.mk</FIlename> has a rule that looks
2677 $(HS_PROG) : $(OBJS)
2678 $(HC) $(LD_OPTS) $< -o $@
2681 <para>If this rule was in
2682 <filename>boilerplate.mk</filename> then
2683 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2685 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2686 would not have their final values at the moment
2687 <command>gmake</command> encountered the rule. Alas,
2688 <command>gmake</command> takes a snapshot of their
2689 current values, and wires that snapshot into the rule.
2690 (In contrast, the commands executed when the rule
2691 “fires” are only substituted at the moment
2692 of firing.) So, the rule must follow the definitions
2693 given in the <filename>Makefile</filename> itself.</para>
2697 <para>Unlike pattern rules, ordinary rules cannot be
2698 overriden or replaced by subsequent rules for the same
2699 target (at least, not without an error message).
2700 Including ordinary rules in
2701 <filename>boilerplate.mk</filename> would prevent the
2702 user from writing rules for specific targets in specific
2707 <para>There are a couple of other reasons I've
2708 forgotten, but it doesn't matter too much.</para>
2715 <sect2 id="sec-boiler">
2716 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2717 <indexterm><primary>boilerplate.mk</primary></indexterm>
2719 <para>If you look at
2720 <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
2721 you will find that it consists of the following sections, each
2722 held in a separate file:</para>
2726 <term><filename>config.mk</filename></term>
2727 <indexterm><primary>config.mk</primary></indexterm>
2729 <para>is the build configuration file we discussed at
2730 length in <Xref LinkEnd="sec-build-config">.</para>
2735 <term><filename>paths.mk</filename></term>
2736 <indexterm><primary>paths.mk</primary></indexterm>
2738 <para>defines <command>make</command> variables for
2739 pathnames and file lists. This file contains code for
2740 automatically compiling lists of source files and deriving
2741 lists of object files from those. The results can be
2742 overriden in the <filename>Makefile</filename>, but in
2743 most cases the automatic setup should do the right
2746 <para>The following variables may be set in the
2747 <filename>Makefile</filename> to affect how the automatic
2748 source file search is done:</para>
2752 <term><literal>ALL_DIRS</literal></term>
2753 <indexterm><primary><literal>ALL_DIRS</literal></primary>
2756 <para>Set to a list of directories to search in
2757 addition to the current directory for source
2763 <term><literal>EXCLUDE_SRCS</literal></term>
2764 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2767 <para>Set to a list of source files (relative to the
2768 current directory) to omit from the automatic
2769 search. The source searching machinery is clever
2770 enough to know that if you exclude a source file
2771 from which other sources are derived, then the
2772 derived sources should also be excluded. For
2773 example, if you set <literal>EXCLUDED_SRCS</literal>
2774 to include <filename>Foo.y</filename>, then
2775 <filename>Foo.hs</filename> will also be
2781 <term><literal>EXTRA_SRCS</literal></term>
2782 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2785 <para>Set to a list of extra source files (perhaps
2786 in directories not listed in
2787 <literal>ALL_DIRS</literal>) that should be
2793 <para>The results of the automatic source file search are
2794 placed in the following make variables:</para>
2798 <term><literal>SRCS</literal></term>
2799 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2801 <para>All source files found, sorted and without
2802 duplicates, including those which might not exist
2803 yet but will be derived from other existing sources.
2804 <literal>SRCS</literal> <emphasis>can</emphasis> be
2805 overriden if necessary, in which case the variables
2806 below will follow suit.</para>
2811 <term><literal>HS_SRCS</literal></term>
2812 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2814 <para>all Haskell source files in the current
2815 directory, including those derived from other source
2816 files (eg. Happy sources also give rise to Haskell
2822 <term><literal>HS_OBJS</literal></term>
2823 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2825 <para>Object files derived from
2826 <literal>HS_SRCS</literal>.</para>
2831 <term><literal>HS_IFACES</literal></term>
2832 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2834 <para>Interface files (<literal>.hi</literal> files)
2835 derived from <literal>HS_SRCS</literal>.</para>
2840 <term><literal>C_SRCS</literal></term>
2841 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2843 <para>All C source files found.</para>
2848 <term><literal>C_OBJS</literal></term>
2849 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2851 <para>Object files derived from
2852 <literal>C_SRCS</literal>.</para>
2857 <term><literal>SCRIPT_SRCS</literal></term>
2858 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2860 <para>All script source files found
2861 (<literal>.lprl</literal> files).</para>
2866 <term><literal>SCRIPT_OBJS</literal></term>
2867 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2869 <para><quote>object</quote> files derived from
2870 <literal>SCRIPT_SRCS</literal>
2871 (<literal>.prl</literal> files).</para>
2876 <term><literal>HSC_SRCS</literal></term>
2877 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2879 <para>All <literal>hsc2hs</literal> source files
2880 (<literal>.hsc</literal> files).</para>
2885 <term><literal>HAPPY_SRCS</literal></term>
2886 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2888 <para>All <literal>happy</literal> source files
2889 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2894 <term><literal>OBJS</literal></term>
2895 <indexterm><primary>OBJS</primary></indexterm>
2897 <para>the concatenation of
2898 <literal>$(HS_OBJS)</literal>,
2899 <literal>$(C_OBJS)</literal>, and
2900 <literal>$(SCRIPT_OBJS)</literal>.</para>
2905 <para>Any or all of these definitions can easily be
2906 overriden by giving new definitions in your
2907 <filename>Makefile</filename>.</para>
2909 <para>What, exactly, does <filename>paths.mk</filename>
2910 consider a <quote>source file</quote> to be? It's based
2911 on the file's suffix (e.g. <filename>.hs</filename>,
2912 <filename>.lhs</filename>, <filename>.c</filename>,
2913 <filename>.hy</filename>, etc), but this is the kind of
2914 detail that changes, so rather than enumerate the source
2915 suffices here the best thing to do is to look in
2916 <filename>paths.mk</filename>.</para>
2921 <term><filename>opts.mk</filename></term>
2922 <indexterm><primary>opts.mk</primary></indexterm>
2924 <para>defines <command>make</command> variables for option
2925 strings to pass to each program. For example, it defines
2926 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2927 the option strings to pass to the Haskell compiler. See
2928 <Xref LinkEnd="sec-suffix">.</para>
2933 <term><filename>suffix.mk</filename></term>
2934 <indexterm><primary>suffix.mk</primary></indexterm>
2936 <para>defines standard pattern rules—see <Xref
2937 LinkEnd="sec-suffix">.</para>
2942 <para>Any of the variables and pattern rules defined by the
2943 boilerplate file can easily be overridden in any particular
2944 <filename>Makefile</filename>, because the boilerplate
2945 <literal>include</literal> comes first. Definitions after this
2946 <literal>include</literal> directive simply override the default
2947 ones in <filename>boilerplate.mk</filename>.</para>
2950 <sect2 id="sec-suffix">
2951 <title>Pattern rules and options</title>
2952 <indexterm><primary>Pattern rules</primary></indexterm>
2955 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2956 defines standard <emphasis>pattern rules</emphasis> that say how
2957 to build one kind of file from another, for example, how to
2958 build a <filename>.o</filename> file from a
2959 <filename>.c</filename> file. (GNU <command>make</command>'s
2960 <emphasis>pattern rules</emphasis> are more powerful and easier
2961 to use than Unix <command>make</command>'s <emphasis>suffix
2962 rules</emphasis>.)</para>
2964 <para>Almost all the rules look something like this:</para>
2969 $(CC) $(CC_OPTS) -c $< -o $@
2972 <para>Here's how to understand the rule. It says that
2973 <emphasis>something</emphasis><filename>.o</filename> (say
2974 <filename>Foo.o</filename>) can be built from
2975 <emphasis>something</emphasis><filename>.c</filename>
2976 (<filename>Foo.c</filename>), by invoking the C compiler (path
2977 name held in <constant>$(CC)</constant>), passing to it
2978 the options <constant>$(CC_OPTS)</constant> and
2979 the rule's dependent file of the rule
2980 <literal>$<</literal> (<filename>Foo.c</filename> in
2981 this case), and putting the result in the rule's target
2982 <literal>$@</literal> (<filename>Foo.o</filename> in this
2985 <para>Every program is held in a <command>make</command>
2986 variable defined in <filename>mk/config.mk</filename>—look
2987 in <filename>mk/config.mk</filename> for the complete list. One
2988 important one is the Haskell compiler, which is called
2989 <constant>$(HC)</constant>.</para>
2991 <para>Every program's options are are held in a
2992 <command>make</command> variables called
2993 <constant><prog>_OPTS</constant>. the
2994 <constant><prog>_OPTS</constant> variables are
2995 defined in <filename>mk/opts.mk</filename>. Almost all of them
2996 are defined like this:</para>
2999 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
3002 <para>The four variables from which
3003 <constant>CC_OPTS</constant> is built have the following
3008 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3010 <para>options passed to all C compilations.</para>
3015 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3017 <para>options passed to C compilations for way
3018 <literal><way></literal>. For example,
3019 <constant>WAY_mp_CC_OPTS</constant>
3020 gives options to pass to the C compiler when compiling way
3021 <literal>mp</literal>. The variable
3022 <constant>WAY_CC_OPTS</constant> holds
3023 options to pass to the C compiler when compiling the
3024 standard way. (<Xref LinkEnd="sec-ways"> dicusses
3025 multi-way compilation.)</para>
3030 <term><constant><module>_CC_OPTS</constant>:</term>
3032 <para>options to pass to the C compiler that are specific
3033 to module <literal><module></literal>. For example,
3034 <constant>SMap_CC_OPTS</constant> gives the
3035 specific options to pass to the C compiler when compiling
3036 <filename>SMap.c</filename>.</para>
3041 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3043 <para>extra options to pass to all C compilations. This
3044 is intended for command line use, thus:</para>
3047 gmake libHS.a EXTRA_CC_OPTS="-v"
3054 <sect2 id="sec-targets">
3055 <title>The main <filename>mk/target.mk</filename> file</title>
3056 <indexterm><primary>target.mk</primary></indexterm>
3058 <para><filename>target.mk</filename> contains canned rules for
3059 all the standard targets described in <Xref
3060 LinkEnd="sec-standard-targets">. It is complicated by the fact
3061 that you don't want all of these rules to be active in every
3062 <filename>Makefile</filename>. Rather than have a plethora of
3063 tiny files which you can include selectively, there is a single
3064 file, <filename>target.mk</filename>, which selectively includes
3065 rules based on whether you have defined certain variables in
3066 your <filename>Makefile</filename>. This section explains what
3067 rules you get, what variables control them, and what the rules
3068 do. Hopefully, you will also get enough of an idea of what is
3069 supposed to happen that you can read and understand any weird
3070 special cases yourself.</para>
3074 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3076 <para>If <constant>HS_PROG</constant> is defined,
3077 you get rules with the following targets:</para>
3081 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3083 <para>itself. This rule links
3084 <constant>$(OBJS)</constant> with the Haskell
3085 runtime system to get an executable called
3086 <constant>$(HS_PROG)</constant>.</para>
3091 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3094 <constant>$(HS_PROG)</constant> in
3095 <constant>$(bindir)</constant>.</para>
3104 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3106 <para>is similar to <constant>HS_PROG</constant>,
3107 except that the link step links
3108 <constant>$(C_OBJS)</constant> with the C
3109 runtime system.</para>
3114 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3116 <para>is similar to <constant>HS_PROG</constant>,
3117 except that it links
3118 <constant>$(LIB_OBJS)</constant> to make the
3119 library archive <constant>$(LIBRARY)</constant>,
3120 and <literal>install</literal> installs it in
3121 <constant>$(libdir)</constant>.</para>
3126 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3128 <para>…</para>
3133 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3135 <para>…</para>
3140 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3142 <para>If <constant>HS_SRCS</constant> is defined
3143 and non-empty, a rule for the target
3144 <literal>depend</literal> is included, which generates
3145 dependency information for Haskell programs. Similarly
3146 for <constant>C_SRCS</constant>.</para>
3151 <para>All of these rules are “double-colon” rules,
3155 install :: $(HS_PROG)
3156 ...how to install it...
3159 <para>GNU <command>make</command> treats double-colon rules as
3160 separate entities. If there are several double-colon rules for
3161 the same target it takes each in turn and fires it if its
3162 dependencies say to do so. This means that you can, for
3163 example, define both <constant>HS_PROG</constant> and
3164 <constant>LIBRARY</constant>, which will generate two rules for
3165 <literal>install</literal>. When you type <command>gmake
3166 install</command> both rules will be fired, and both the program
3167 and the library will be installed, just as you wanted.</para>
3170 <sect2 id="sec-subdirs">
3171 <title>Recursion</title>
3172 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3173 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3175 <para>In leaf <filename>Makefile</filename>s the variable
3176 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3177 is undefined. In non-leaf <filename>Makefile</filename>s,
3178 <constant>SUBDIRS</constant> is set to the list of
3179 sub-directories that contain subordinate
3180 <filename>Makefile</filename>s. <emphasis>It is up to you to
3181 set <constant>SUBDIRS</constant> in the
3182 <filename>Makefile</filename>.</emphasis> There is no automation
3183 here—<constant>SUBDIRS</constant> is too important to
3186 <para>When <constant>SUBDIRS</constant> is defined,
3187 <filename>target.mk</filename> includes a rather neat rule for
3188 the standard targets (<Xref LinkEnd="sec-standard-targets"> that
3189 simply invokes <command>make</command> recursively in each of
3190 the sub-directories.</para>
3192 <para><emphasis>These recursive invocations are guaranteed to
3193 occur in the order in which the list of directories is specified
3194 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3195 be important. For example, when you say <command>gmake
3196 boot</command> it can be important that the recursive invocation
3197 of <command>make boot</command> is done in one sub-directory
3198 (the include files, say) before another (the source files).
3199 Generally, put the most independent sub-directory first, and the
3200 most dependent last.</para>
3203 <sect2 id="sec-ways">
3204 <title>Way management</title>
3205 <indexterm><primary>way management</primary></indexterm>
3207 <para>We sometimes want to build essentially the same system in
3208 several different “ways”. For example, we want to build GHC's
3209 <literal>Prelude</literal> libraries with and without profiling,
3210 so that there is an appropriately-built library archive to link
3211 with when the user compiles his program. It would be possible
3212 to have a completely separate build tree for each such “way”,
3213 but it would be horribly bureaucratic, especially since often
3214 only parts of the build tree need to be constructed in multiple
3218 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3219 contains some clever magic to allow you to build several
3220 versions of a system; and to control locally how many versions
3221 are built and how they differ. This section explains the
3224 <para>The files for a particular way are distinguished by
3225 munging the suffix. The <quote>normal way</quote> is always
3226 built, and its files have the standard suffices
3227 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3228 In addition, you can build one or more extra ways, each
3229 distinguished by a <emphasis>way tag</emphasis>. The object
3230 files and interface files for one of these extra ways are
3231 distinguished by their suffix. For example, way
3232 <literal>mp</literal> has files
3233 <filename>.mp_o</filename> and
3234 <filename>.mp_hi</filename>. Library archives have their
3235 way tag the other side of the dot, for boring reasons; thus,
3236 <filename>libHS_mp.a</filename>.</para>
3238 <para>A <command>make</command> variable called
3239 <constant>way</constant> holds the current way tag.
3240 <emphasis><constant>way</constant> is only ever set on the
3241 command line of <command>gmake</command></emphasis> (usually in
3242 a recursive invocation of <command>gmake</command> by the
3243 system). It is never set inside a
3244 <filename>Makefile</filename>. So it is a global constant for
3245 any one invocation of <command>gmake</command>. Two other
3246 <command>make</command> variables,
3247 <constant>way_</constant> and
3248 <constant>_way</constant> are immediately derived from
3249 <constant>$(way)</constant> and never altered. If
3250 <constant>way</constant> is not set, then neither are
3251 <constant>way_</constant> and
3252 <constant>_way</constant>, and the invocation of
3253 <command>make</command> will build the <quote>normal
3254 way</quote>. If <constant>way</constant> is set, then the other
3255 two variables are set in sympathy. For example, if
3256 <constant>$(way)</constant> is “<literal>mp</literal>”,
3257 then <constant>way_</constant> is set to
3258 “<literal>mp_</literal>” and
3259 <constant>_way</constant> is set to
3260 “<literal>_mp</literal>”. These three variables are
3261 then used when constructing file names.</para>
3263 <para>So how does <command>make</command> ever get recursively
3264 invoked with <constant>way</constant> set? There are two ways
3265 in which this happens:</para>
3269 <para>For some (but not all) of the standard targets, when
3270 in a leaf sub-directory, <command>make</command> is
3271 recursively invoked for each way tag in
3272 <constant>$(WAYS)</constant>. You set
3273 <constant>WAYS</constant> in the
3274 <filename>Makefile</filename> to the list of way tags you
3275 want these targets built for. The mechanism here is very
3276 much like the recursive invocation of
3277 <command>make</command> in sub-directories (<Xref
3278 LinkEnd="sec-subdirs">). It is up to you to set
3279 <constant>WAYS</constant> in your
3280 <filename>Makefile</filename>; this is how you control what
3281 ways will get built.</para>
3285 <para>For a useful collection of targets (such as
3286 <filename>libHS_mp.a</filename>,
3287 <filename>Foo.mp_o</filename>) there is a rule which
3288 recursively invokes <command>make</command> to make the
3289 specified target, setting the <constant>way</constant>
3290 variable. So if you say <command>gmake
3291 Foo.mp_o</command> you should see a recursive
3292 invocation <command>gmake Foo.mp_o way=mp</command>,
3293 and <emphasis>in this recursive invocation the pattern rule
3294 for compiling a Haskell file into a <filename>.o</filename>
3295 file will match</emphasis>. The key pattern rules (in
3296 <filename>suffix.mk</filename>) look like this:
3300 $(HC) $(HC_OPTS) $< -o $@
3307 <para>You can invoke <command>make</command> with a
3308 particular <literal>way</literal> setting yourself, in order
3309 to build files related to a particular
3310 <literal>way</literal> in the current directory. eg.
3316 will build files for the profiling way only in the current
3323 <title>When the canned rule isn't right</title>
3325 <para>Sometimes the canned rule just doesn't do the right thing.
3326 For example, in the <literal>nofib</literal> suite we want the
3327 link step to print out timing information. The thing to do here
3328 is <emphasis>not</emphasis> to define
3329 <constant>HS_PROG</constant> or
3330 <constant>C_PROG</constant>, and instead define a special
3331 purpose rule in your own <filename>Makefile</filename>. By
3332 using different variable names you will avoid the canned rules
3333 being included, and conflicting with yours.</para>
3337 <sect1 id="building-docs">
3338 <title>Building the documentation</title>
3340 <sect2 id="pre-supposed-doc-tools">
3341 <title>Tools for building the Documentation</title>
3343 <para>The following additional tools are required if you want to
3344 format the documentation that comes with the
3345 <literal>fptools</literal> projects:</para>
3349 <term>DocBook</term>
3350 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3351 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3353 <para>Much of our documentation is written in SGML, using
3354 the DocBook DTD. Instructions on installing and
3355 configuring the DocBook tools are below.</para>
3361 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3362 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3364 <para>A decent TeX distribution is required if you want to
3365 produce printable documentation. We recomment teTeX,
3366 which includes just about everything you need.</para>
3371 <term>Haddock</term>
3372 <indexterm><primary>Haddock</primary>
3375 <para>Haddock is a Haskell documentation tool that we use
3376 for automatically generating documentation from the
3377 library source code. It is an <literal>fptools</literal>
3378 project in itself. To build documentation for the
3379 libraries (<literal>fptools/libraries</literal>) you
3380 should check out and build Haddock in
3381 <literal>fptools/haddock</literal>. Haddock requires GHC
3389 <title>Installing the DocBook tools</title>
3392 <title>Installing the DocBook tools on Linux</title>
3394 <para>If you're on a recent RedHat system (7.0+), you probably
3395 have working DocBook tools already installed. The configure
3396 script should detect your setup and you're away.</para>
3398 <para>If you don't have DocBook tools installed, and you are
3399 using a system that can handle RedHat RPM packages, you can
3400 probably use the <ULink
3401 URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3402 DocBook tools</ULink>, which is the most shrink-wrapped SGML
3403 suite that we could find. You need all the RPMs except for
3404 psgml (i.e. <Filename>docbook</Filename>,
3405 <Filename>jade</Filename>, <Filename>jadetex</Filename>,
3406 <Filename>sgmlcommon</Filename> and
3407 <Filename>stylesheets</Filename>). Note that most of these
3408 RPMs are architecture neutral, so are likely to be found in a
3409 <Filename>noarch</Filename> directory. The SuSE RPMs also
3410 work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
3411 (7.0 and later should be OK), but they are easy to fix: just
3413 <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
3414 to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
3418 <title>Installing DocBook on FreeBSD</title>
3420 <para>On FreeBSD systems, the easiest way to get DocBook up
3421 and running is to install it from the ports tree or a
3422 pre-compiled package (packages are available from your local
3423 FreeBSD mirror site).</para>
3425 <para>To use the ports tree, do this:
3427 $ cd /usr/ports/textproc/docproj
3430 This installs the FreeBSD documentation project tools, which
3431 includes everything needed to format the GHC
3432 documentation.</para>
3436 <title>Installing from binaries on Windows</title>
3438 <Para>It's a good idea to use Norman Walsh's <ULink
3439 URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3440 notes</ULink> as a guide. You should get version 3.1 of
3441 DocBook, and note that his file <Filename>test.sgm</Filename>
3442 won't work, as it needs version 3.0. You should unpack Jade
3443 into <Filename>\Jade</Filename>, along with the entities,
3444 DocBook into <Filename>\docbook</Filename>, and the DocBook
3445 stylesheets into <Filename>\docbook\stylesheets</Filename> (so
3446 they actually end up in
3447 <Filename>\docbook\stylesheets\docbook</Filename>).</para>
3452 <title>Installing the DocBook tools from source</title>
3457 <para>Install <ULink
3458 URL="http://openjade.sourceforge.net/">OpenJade</ULink>
3459 (Windows binaries are available as well as sources). If you
3460 want DVI, PS, or PDF then install JadeTeX from the
3461 <Filename>dsssl</Filename> subdirectory. (If you get the
3465 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
3468 your version of <Command>hyperref</Command> is out of date;
3469 download it from CTAN
3470 (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
3471 and make it, ensuring that you have first removed or renamed
3472 your old copy. If you start getting file not found errors
3473 when making the test for <Command>hyperref</Command>, you
3474 can abort at that point and proceed straight to
3475 <Command>make install</Command>, or enter them as
3476 <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
3478 <para>Make links from <Filename>virtex</Filename> to
3479 <Filename>jadetex</Filename> and
3480 <Filename>pdfvirtex</Filename> to
3481 <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
3482 and PDF output will not work). Copy
3483 <Filename>dsssl/*.{dtd,dsl}</Filename> and
3484 <Filename>catalog</Filename> to
3485 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3489 <title>DocBook and the DocBook stylesheets</title>
3491 <para>Get a Zip of <ULink
3492 URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
3493 and install the contents in
3494 <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
3496 <para>Get the <ULink
3497 URL="http://nwalsh.com/docbook/dsssl/">DocBook
3498 stylesheets</ULink> and install in
3499 <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
3500 (thereby creating a subdirectory docbook). For indexing,
3501 copy or link <Filename>collateindex.pl</Filename> from the
3502 DocBook stylesheets archive in <Filename>bin</Filename> into
3503 a directory on your <Constant>PATH</Constant>.</para>
3505 <para>Download the <ULink
3506 URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3507 entities</ULink> into
3508 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3514 <title>Configuring the DocBook tools</title>
3516 <Para>Once the DocBook tools are installed, the configure script
3517 will detect them and set up the build system accordingly. If you
3518 have a system that isn't supported, let us know, and we'll try
3523 <title>Remaining problems</title>
3525 <para>If you install from source, you'll get a pile of warnings
3528 <Screen>DTDDECL catalog entries are not supported</Screen>
3530 every time you build anything. These can safely be ignored, but
3531 if you find them tedious you can get rid of them by removing all
3532 the <Constant>DTDDECL</Constant> entries from
3533 <Filename>docbook.cat</Filename>.</para>
3537 <title>Building the documentation</title>
3539 <para>To build documentation in a certain format, you can
3540 say, for example,</para>
3546 <para>to build HTML documentation below the current directory.
3547 The available formats are: <literal>dvi</literal>,
3548 <literal>ps</literal>, <literal>pdf</literal>,
3549 <literal>html</literal>, and <literal>rtf</literal>. Note that
3550 not all documentation can be built in all of these formats: HTML
3551 documentation is generally supported everywhere, and DocBook
3552 documentation might support the other formats (depending on what
3553 other tools you have installed).</para>
3555 <para>All of these targets are recursive; that is, saying
3556 <literal>make html</literal> will make HTML docs for all the
3557 documents recursively below the current directory.</para>
3559 <para>Because there are many different formats that the DocBook
3560 documentation can be generated in, you have to select which ones
3561 you want by setting the <literal>SGMLDocWays</literal> variable
3562 to a list of them. For example, in
3563 <filename>build.mk</filename> you might have a line:</para>
3566 SGMLDocWays = html ps
3569 <para>This will cause the documentation to be built in the requested
3570 formats as part of the main build (the default is not to build
3571 any documentation at all).</para>
3575 <title>Installing the documentation</title>
3577 <para>To install the documentation, use:</para>
3583 <para>This will install the documentation into
3584 <literal>$(datadir)</literal> (which defaults to
3585 <literal>$(prefix)/share</literal>). The exception is HTML
3586 documentation, which goes into
3587 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3589 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3590 to a list of formats, the <literal>install-docs</literal> target
3591 won't do anything for SGML documentation.</para>
3597 <sect1 id="sec-porting-ghc">
3598 <title>Porting GHC</title>
3600 <para>This section describes how to port GHC to a currenly
3601 unsupported platform. There are two distinct
3602 possibilities:</para>
3606 <para>The hardware architecture for your system is already
3607 supported by GHC, but you're running an OS that isn't
3608 supported (or perhaps has been supported in the past, but
3609 currently isn't). This is the easiest type of porting job,
3610 but it still requires some careful bootstrapping. Proceed to
3611 <xref linkend="sec-booting-from-hc">.</para>
3615 <para>Your system's hardware architecture isn't supported by
3616 GHC. This will be a more difficult port (though by comparison
3617 perhaps not as difficult as porting gcc). Proceed to <xref
3618 linkend="unregisterised-porting">.</para>
3622 <sect2 id="sec-booting-from-hc">
3623 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3625 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3626 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3627 <indexterm><primary>porting GHC</primary></indexterm>
3629 <para>Bootstrapping GHC on a system without GHC already
3630 installed is achieved by taking the intermediate C files (known
3631 as HC files) from a GHC compilation on a supported system to the
3632 target machine, and compiling them using gcc to get a working
3635 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3636 from C. We recommend using GHC 6.0.1 or
3637 later.</emphasis></para>
3639 <para>HC files are platform-dependent, so you have to get a set
3640 that were generated on similar hardware. There may be some
3641 supplied on the GHC download page, otherwise you'll have to
3642 compile some up yourself, or start from
3643 <emphasis>unregisterised</emphasis> HC files - see <xref
3644 linkend="unregisterised-porting">.</para>
3646 <para>The following steps should result in a working GHC build
3647 with full libraries:</para>
3651 <para>Unpack the HC files on top of a fresh source tree
3652 (make sure the source tree version matches the version of
3653 the HC files <emphasis>exactly</emphasis>!). This will
3654 place matching <filename>.hc</filename> files next to the
3655 corresponding Haskell source (<filename>.hs</filename> or
3656 <filename>.lhs</filename>) in the compiler subdirectory
3657 <filename>ghc/compiler</filename> and in the libraries
3658 (subdirectories of <filename>hslibs</filename> and
3659 <literal>libraries</literal>).</para>
3663 <para>The actual build process is fully automated by the
3664 <filename>hc-build</filename> script located in the
3665 <filename>distrib</filename> directory. If you eventually
3666 want to install GHC into the directory
3667 <replaceable>dir</replaceable>, the following
3668 command will execute the whole build process (it won't
3669 install yet):</para>
3672 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3674 <indexterm><primary>--hc-build</primary></indexterm>
3676 <para>By default, the installation directory is
3677 <filename>/usr/local</filename>. If that is what you want,
3678 you may omit the argument to <filename>hc-build</filename>.
3679 Generally, any option given to <filename>hc-build</filename>
3680 is passed through to the configuration script
3681 <filename>configure</filename>. If
3682 <filename>hc-build</filename> successfully completes the
3683 build process, you can install the resulting system, as
3693 <sect2 id="unregisterised-porting">
3694 <title>Porting GHC to a new architecture</title>
3696 <para>The first step in porting to a new architecture is to get
3697 an <firstterm>unregisterised</firstterm> build working. An
3698 unregisterised build is one that compiles via vanilla C only.
3699 By contrast, a registerised build uses the following
3700 architecture-specific hacks for speed:</para>
3704 <para>Global register variables: certain abstract machine
3705 <quote>registers</quote> are mapped to real machine
3706 registers, depending on how many machine registers are
3708 <filename>ghc/includes/MachRegs.h</filename>).</para>
3712 <para>Assembly-mangling: when compiling via C, we feed the
3713 assembly generated by gcc though a Perl script known as the
3714 <firstterm>mangler</firstterm> (see
3715 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3716 mangler rearranges the assembly to support tail-calls and
3717 various other optimisations.</para>
3721 <para>In an unregisterised build, neither of these hacks are
3722 used — the idea is that the C code generated by the
3723 compiler should compile using gcc only. The lack of these
3724 optimisations costs about a factor of two in performance, but
3725 since unregisterised compilation is usually just a step on the
3726 way to a full registerised port, we don't mind too much.</para>
3728 <para>Notes on GHC portability in general: we've tried to stick
3729 to writing portable code in most parts of the system, so it
3730 should compile on any POSIXish system with gcc, but in our
3731 experience most systems differ from the standards in one way or
3732 another. Deal with any problems as they arise - if you get
3733 stuck, ask the experts on
3734 <email>glasgow-haskell-users@haskell.org</email>.</para>
3736 <para>Lots of useful information about the innards of GHC is
3737 available in the <ulink
3738 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3739 Commentary</ulink>, which might be helpful if you run into some
3740 code which needs tweaking for your system.</para>
3743 <title>Cross-compiling to produce an unregisterised GHC</title>
3745 <para>In this section, we explain how to bootstrap GHC on a
3746 new platform, using unregisterised intermediate C files. We
3747 haven't put a great deal of effort into automating this
3748 process, for two reasons: it is done very rarely, and the
3749 process usually requires human intervention to cope with minor
3750 porting issues anyway.</para>
3752 <para>The following step-by-step instructions should result in
3753 a fully working, albeit unregisterised, GHC. Firstly, you
3754 need a machine that already has a working GHC (we'll call this
3755 the <firstterm>host</firstterm> machine), in order to
3756 cross-compile the intermediate C files that we will use to
3757 bootstrap the compiler on the <firstterm>target</firstterm>
3762 <para>On the target machine:</para>
3766 <para>Unpack a source tree (preferably a released
3767 version). We will call the path to the root of this
3768 tree <replaceable>T</replaceable>.</para>
3773 $ cd <replaceable>T</replaceable>
3774 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
3777 <para>You might need to update
3778 <filename>configure.in</filename> to recognise the new
3779 architecture, and re-generate
3780 <filename>configure</filename> with
3781 <literal>autoreconf</literal>.</para>
3786 $ cd <replaceable>T</replaceable>/ghc/includes
3794 <para>On the host machine:</para>
3798 <para>Unpack a source tree (same released version). Call
3799 this directory <replaceable>H</replaceable>.</para>
3804 $ cd <replaceable>H</replaceable>
3811 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3812 with the following contents:</para>
3815 GhcUnregisterised = YES
3816 GhcLibHcOpts = -O -H32m -keep-hc-files
3819 GhcWithNativeCodeGen = NO
3820 GhcWithInterpreter = NO
3821 GhcStage1HcOpts = -O -H32m -fasm
3822 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3828 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3831 <para>change <literal>TARGETPLATFORM</literal>
3832 appropriately, and set the variables involving
3833 <literal>TARGET</literal> to the correct values for
3834 the target platform. This step is necessary because
3835 currently <literal>configure</literal> doesn't cope
3836 with specifying different values for the
3837 <literal>--host</literal> and
3838 <literal>--target</literal> flags.</para>
3841 <para>copy <literal>LeadingUnderscore</literal>
3842 setting from target.</para>
3849 <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
3851 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3852 Note that we are building on the host machine, using the
3853 target machine's <literal>config.h</literal> file. This
3854 is so that the intermediate C files generated here will
3855 be suitable for compiling on the target system.</para>
3860 <para>Touch <literal>config.h</literal>, just to make
3861 sure it doesn't get replaced during the build:</para>
3863 $ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
3867 <para>Now build the compiler:</para>
3869 $ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3870 $ cd <replaceable>H</replaceable>/ghc && make boot && make
3872 <para>Don't worry if the build falls over in the RTS, we
3873 don't need the RTS yet.</para>
3878 $ cd <replaceable>H</replaceable>/libraries
3879 $& make boot && make
3885 $ cd <replaceable>H</replaceable>/ghc
3886 $ make boot stage=2 && make stage=2
3892 $ cd <replaceable>H</replaceable>/ghc/utils
3894 $ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
3895 EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3901 $ cd <replaceable>H</replaceable>
3902 $ make hc-file-bundle Project=Ghc
3908 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3909 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3915 <para>On the target machine:</para>
3917 <para>At this stage we simply need to bootstrap a compiler
3918 from the intermediate C files we generated above. The
3919 process of bootstrapping from C files is automated by the
3920 script in <literal>distrib/hc-build</literal>, and is
3921 described in <xref linkend="sec-booting-from-hc">.</para>
3924 $ ./distrib/hc-build --enable-hc-boot-unregisterised
3927 <para>However, since this is a bootstrap on a new machine,
3928 the automated process might not run to completion the
3929 first time. For that reason, you might want to treat the
3930 <literal>hc-build</literal> script as a list of
3931 instructions to follow, rather than as a fully automated
3932 script. This way you'll be able to restart the process
3933 part-way through if you need to fix anything on the
3936 <para>Don't bother with running
3937 <literal>make install</literal> in the newly
3938 bootstrapped tree; just use the compiler in that tree to
3939 build a fresh compiler from scratch, this time without
3940 booting from C files. Before doing this, you might want
3941 to check that the bootstrapped compiler is generating
3942 working binaries:</para>
3946 main = putStrLn "Hello World!\n"
3948 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3953 <para>Once you have the unregisterised compiler up and
3954 running, you can use it to start a registerised port. The
3955 following sections describe the various parts of the
3956 system that will need architecture-specific tweaks in
3957 order to get a registerised build going.</para>
3964 <title>Porting the RTS</title>
3966 <para>The following files need architecture-specific code for a
3967 registerised build:</para>
3971 <term><filename>ghc/includes/MachRegs.h</filename></term>
3972 <indexterm><primary><filename>MachRegs.h</filename></primary>
3975 <para>Defines the STG-register to machine-register
3976 mapping. You need to know your platform's C calling
3977 convention, and which registers are generally available
3978 for mapping to global register variables. There are
3979 plenty of useful comments in this file.</para>
3983 <term><filename>ghc/includes/TailCalls.h</filename></term>
3984 <indexterm><primary><filename>TailCalls.h</filename></primary>
3987 <para>Macros that cooperate with the mangler (see <xref
3988 linkend="sec-mangler">) to make proper tail-calls
3993 <term><filename>ghc/rts/Adjustor.c</filename></term>
3994 <indexterm><primary><filename>Adjustor.c</filename></primary>
3998 <literal>foreign import "wrapper"</literal>
4000 <literal>foreign export dynamic</literal>).
4001 Not essential for getting GHC bootstrapped, so this file
4002 can be deferred until later if necessary.</para>
4006 <term><filename>ghc/rts/StgCRun.c</filename></term>
4007 <indexterm><primary><filename>StgCRun.c</filename></primary>
4010 <para>The little assembly layer between the C world and
4011 the Haskell world. See the comments and code for the
4012 other architectures in this file for pointers.</para>
4016 <term><filename>ghc/rts/MBlock.h</filename></term>
4017 <term><filename>ghc/rts/MBlock.c</filename></term>
4018 <indexterm><primary><filename>MBlock.h</filename></primary>
4020 <indexterm><primary><filename>MBlock.c</filename></primary>
4023 <para>These files are really OS-specific rather than
4024 architecture-specific. In <filename>MBlock.h</filename>
4025 is specified the absolute location at which the RTS
4026 should try to allocate memory on your platform (try to
4027 find an area which doesn't conflict with code or dynamic
4028 libraries). In <filename>Mblock.c</filename> you might
4029 need to tweak the call to <literal>mmap()</literal> for
4036 <sect3 id="sec-mangler">
4037 <title>The mangler</title>
4039 <para>The mangler is an evil Perl-script that rearranges the
4040 assembly code output from gcc to do two main things:</para>
4044 <para>Remove function prologues and epilogues, and all
4045 movement of the C stack pointer. This is to support
4046 tail-calls: every code block in Haskell code ends in an
4047 explicit jump, so we don't want the C-stack overflowing
4048 while we're jumping around between code blocks.</para>
4051 <para>Move the <firstterm>info table</firstterm> for a
4052 closure next to the entry code for that closure. In
4053 unregisterised code, info tables contain a pointer to the
4054 entry code, but in registerised compilation we arrange
4055 that the info table is shoved right up against the entry
4056 code, and addressed backwards from the entry code pointer
4057 (this saves a word in the info table and an extra
4058 indirection when jumping to the closure entry
4063 <para>The mangler is abstracted to a certain extent over some
4064 architecture-specific things such as the particular assembler
4065 directives used to herald symbols. Take a look at the
4066 definitions for other architectures and use these as a
4067 starting point.</para>
4071 <title>The native code generator</title>
4073 <para>The native code generator isn't essential to getting a
4074 registerised build going, but it's a desirable thing to have
4075 because it can cut compilation times in half. The native code
4076 generator is described in some detail in the <ulink
4077 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
4078 commentary</ulink>.</para>
4084 <para>To support GHCi, you need to port the dynamic linker
4085 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
4086 currently supports the ELF and PEi386 object file formats - if
4087 your platform uses one of these then you probably don't have
4088 to do anything except fiddle with the
4089 <literal>#ifdef</literal>s at the top of
4090 <filename>Linker.c</filename> to tell it about your OS.</para>
4092 <para>If your system uses a different object file format, then
4093 you have to write a linker — good luck!</para>
4099 <sect1 id="sec-build-pitfalls">
4100 <title>Known pitfalls in building Glasgow Haskell
4102 <indexterm><primary>problems, building</primary></indexterm>
4103 <indexterm><primary>pitfalls, in building</primary></indexterm>
4104 <indexterm><primary>building pitfalls</primary></indexterm></title>
4107 WARNINGS about pitfalls and known “problems”:
4116 One difficulty that comes up from time to time is running out of space
4117 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
4118 compensate for the vagaries of different sysadmin approaches to temp
4120 <indexterm><primary>tmp, running out of space in</primary></indexterm>
4122 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
4123 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
4126 The best way around it is to say
4129 export TMPDIR=<dir>
4132 in your <filename>build.mk</filename> file.
4133 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
4142 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
4143 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
4151 When compiling via C, you'll sometimes get “warning: assignment from
4152 incompatible pointer type” out of GCC. Harmless.
4159 Similarly, <command>ar</command>chiving warning messages like the following are not
4163 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
4164 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
4174 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
4175 get an “Out of heap space” error message. These can vary with the
4176 vagaries of different systems, it seems. The solution is simple:
4183 If you're compiling with GHC 4.00 or later, then the
4184 <emphasis>maximum</emphasis> heap size must have been reached. This
4185 is somewhat unlikely, since the maximum is set to 64M by default.
4186 Anyway, you can raise it with the
4187 <option>-optCrts-M<size></option> flag (add this flag to
4188 <constant><module>_HC_OPTS</constant>
4189 <command>make</command> variable in the appropriate
4190 <filename>Makefile</filename>).
4197 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4206 and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
4207 <constant><module>_HC_OPTS</constant>.)
4209 Alternatively, just cut to the chase:
4213 % make EXTRA_HC_OPTS=-optCrts-M128M
4222 If you try to compile some Haskell, and you get errors from GCC about
4223 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4224 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4226 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4227 this bug also suggests that you have an old GCC.
4235 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4239 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4240 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4242 ? # or, on some machines: ar s $i
4247 We'd be interested to know if this is still necessary.
4255 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4256 a bit from one Unix to another. One particular gotcha is macro calls
4261 SLIT("Hello, world")
4265 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4266 arguments, so you get
4270 :731: macro `SLIT' used with too many (2) args
4274 Alas, <command>cpp</command> doesn't tell you the offending file!
4276 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4287 <Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
4290 This section summarises how to get the utilities you need on your
4291 Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
4292 installing and running GHC may be found in the user guide. In general,
4293 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4294 You should read the GHC installation guide sections on Windows (in the user
4295 guide) before continuing to read these notes.
4299 <sect2 id="cygwin-and-mingw"><Title>Cygwin and MinGW</Title>
4301 <para> The Windows situation for building GHC is rather confusing. This section
4302 tries to clarify, and to establish terminology.</para>
4304 <sect3 id="ghc-mingw"><title>GHC-mingw</title>
4306 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4307 is a collection of header
4308 files and import libraries that allow one to use <command>gcc</command> and produce
4309 native Win32 programs that do not rely on any third-party DLLs. The
4310 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4311 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4314 <para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
4315 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4316 GHC compiles Haskell to C (or to
4317 assembly code), and then invokes these MinGW tools to generate an executable binary.
4318 The resulting binaries can run on any Win32 system.
4320 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4322 <para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
4323 Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
4324 library; they have to do
4325 their input output using standard Haskell I/O libraries, or native Win32 bindings.
4329 <sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
4331 <para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
4332 <ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
4333 Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
4334 <command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
4335 A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
4337 <para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
4338 Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
4339 A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
4340 If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
4341 that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
4342 Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4343 does not change, but the implementation certainly does. Even the interfaces to functions
4344 it exports seem to change occasionally. So programs compiled by GHC might only run with
4345 particular versions of Cygwin. All of this seems very undesirable.
4348 Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
4349 we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
4350 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4354 <sect3><title>HOST_OS vs TARGET_OS</title>
4357 In the source code you'll find various ifdefs looking like:
4359 #ifdef mingw32_HOST_OS
4365 #ifdef mingw32_TARGET_OS
4369 These macros are set by the configure script (via the file config.h).
4370 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4373 The "host" system is the one on which GHC itself will be run.
4376 The "target" system is the one for which the program compiled by GHC will be run.
4379 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4380 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4385 <sect3><title>Summary</title>
4387 <para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
4388 how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
4389 by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
4391 <para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
4392 GHC-cygwin too is beyond our resources. The GHC we distribute
4393 therefore does not require Cygwin to run, nor do the programs it
4394 compiles require Cygwin.</para>
4396 <para>The instructions that follow describe how to build GHC-mingw. It is
4397 possible to build GHC-cygwin, but it's not a supported route, and the build system might
4400 <para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>. It
4401 uses the <Command>gcc</Command> that you specify using the
4402 <option>--with-gcc</option> flag when you run
4403 <Command>configure</Command> (see below).
4404 The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
4405 to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
4406 whatever one happens to be in your path. However, the makefiles do use whatever <Command>ld</Command>
4407 and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
4408 used to glom together .o files into a bigger .o file, or a .a file,
4409 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4410 Cygwin and Mingw use the same .o file format. So its ok.
4415 <Sect2><Title>Installing and configuring Cygwin</Title>
4417 <para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
4418 but you do need it to <emphasis>build</emphasis> GHC.</para>
4420 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4421 The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
4422 During the installation dialogue, make sure that you select:
4423 <command>cvs</command>, <command>openssh</command>,
4424 <command>autoconf</command>,
4425 <command>binutils</command> (includes ld and (I think) ar),
4426 <command>gcc</command>,
4427 <command>flex</command>,
4428 <command>make</command>.
4431 <para> Now set the following user environment variables:
4434 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4435 <constant>PATH</constant></para></listitem>
4439 Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
4440 don't do this you get very weird messages when you type
4441 <Command>make</Command>, such as:
4443 /c: /c: No such file or directory
4448 <listitem><para> Set <constant>SHELL</constant> to
4449 <Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
4450 <constant>SHELL</constant> is what you get.
4453 <listitem><para> Set <constant>HOME</constant> to point to your
4454 home directory. This is where, for example,
4455 <command>bash</command> will look for your <filename>.bashrc</filename>
4456 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4462 There are a few other things to do:
4466 By default, cygwin provides the command shell <filename>ash</filename>
4467 as <filename>sh.exe</filename>. We have often seen build-system problems that
4468 turn out to be due to bugs in <filename>ash</filename>
4470 and length of command lines). On the other hand <filename>bash</filename> seems
4472 So, in <filename>cygwin/bin</filename>
4473 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4474 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4475 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4476 you can't rename a running program!
4482 Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
4483 (and similarly for <Command>sh</Command>). Notice the hardwired path!
4484 So you need to ensure that your <Filename>/bin</Filename> directory has the following
4487 <listitem> <para><Command>sh</Command></para></listitem>
4488 <listitem> <para><Command>perl</Command></para></listitem>
4489 <listitem> <para><Command>cat</Command></para></listitem>
4491 All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
4492 installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
4493 <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
4494 (You can discover where your Cygwin
4495 root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
4496 Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
4497 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4498 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4504 <para>Finally, here are some things to be aware of when using Cygwin:
4506 <listitem> <para>Cygwin doesn't deal well with filenames that include
4507 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4511 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4512 magical text in it. So other programs that don't use Cygwin's
4513 I/O libraries won't recognise such files as symlinks.
4514 In particular, programs compiled by GHC are meant to be runnable
4515 without having Cygwin, so they don't use the Cygwin library, so
4516 they don't recognise symlinks.
4520 Win32 has a <command>find</command> command which is not the same as Cygwin's find.
4521 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4522 before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4523 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4524 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4531 <Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
4533 <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
4534 you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
4535 (not ssh) in the Cygwin list of applications!</para>
4537 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
4541 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
4542 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
4543 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
4544 and run it as follows:
4546 c:\tmp> set CYGWIN32=tty
4547 c:\tmp> c:/user/local/bin/ssh-keygen1
4552 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
4553 To determine your home directory <command>ssh</command> first looks in
4554 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
4555 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
4556 the setting of the environment variable $HOME</emphasis>. If the home directory is
4557 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
4559 ssh -v cvs.haskell.org
4561 which makes <command>ssh</command> print out information about its activity.
4563 <para> You can fix this problem, either by correcting the home-directory field in
4564 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
4565 you do that, <command>ssh</command> uses the $HOME environment variable instead.
4571 <para>To protect your
4572 <literal>.ssh</literal> from access by anyone else,
4573 right-click your <literal>.ssh</literal> directory, and
4574 select <literal>Properties</literal>. If you are not on
4575 the access control list, add yourself, and give yourself
4576 full permissions (the second panel). Remove everyone else
4577 from the access control list. Don't leave them there but
4578 deny them access, because 'they' may be a list that
4579 includes you!</para>
4583 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4584 you to have Unix permissions 600 (read/write for owner only)
4585 on the <literal>.ssh/identity</literal> file, else it
4586 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4587 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4588 The solution seems to be to set the $CYGWIN environment
4589 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4590 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4591 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4598 <Sect2><Title>Other things you need to install</Title>
4600 <para>You have to install the following other things to build GHC:
4604 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4605 This is what you will use to compile GHC. Add it in your
4606 <constant>PATH</constant>: the installer tells you the path element
4607 you need to add upon completion.
4613 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4614 Happy is a parser generator used to compile the Haskell grammar. Add it in your
4615 <constant>PATH</constant>.
4620 <para>Install Alex. This can be done by building from the
4621 source distribution in the usual way. Sources are
4622 available from <ulink
4623 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4627 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4628 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">).
4629 Just pick up a mingw bundle at
4630 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4631 We install it in <filename>c:/mingw</filename>.
4633 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4634 They are only going to get used by explicit access (via the --with-gcc flag you
4635 give to <Command>configure</Command> later). If you do add them to your path
4636 you are likely to get into a mess because their names overlap with Cygwin binaries.
4642 <para>We use <command>emacs</command> a lot, so we install that too.
4643 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4644 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4645 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4646 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4647 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4648 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4654 <para> Finally, check out a copy of GHC sources from
4655 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
4662 <Sect2><Title>Building GHC</Title>
4665 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
4666 the bullets below only tell
4667 you about Windows-specific wrinkles.</para>
4671 Run <Command>autoconf</Command> both in <filename>fptools</filename>
4672 and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
4673 get an error when you run <filename>./configure</filename>:
4676 creating mk/config.h
4677 mk/config.h is unchanged
4679 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4680 ./configure: ./configure: No such file or directory
4681 configure: error: ./configure failed for ghc
4686 <listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
4687 read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
4690 /usr/bin/autoconf: cannot create configure: permission denied
4692 Solution: delete <filename>configure</filename> first.
4697 You either need to add <filename>ghc</filename> to your
4698 <constant>PATH</constant> before you invoke
4699 <Command>configure</Command>, or use the <Command>configure</Command>
4700 option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
4705 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4706 This file occasionally remembers out-of-date configuration information, which
4707 can be really confusing.
4713 After <command>autoconf</command> run <command>./configure</command> in
4714 <filename>fptools/</filename> thus:
4717 ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
4719 This is the point at which you specify that you are building GHC-mingw
4720 (see <xref linkend="ghc-mingw">). </para>
4722 <para> Both these options are important! It's possible to get into
4723 trouble using the wrong C compiler!</para>
4725 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4726 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4727 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4728 understand a Cygwin path. For example, if you
4729 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4730 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4731 time it tries to invoke it. Worse, the failure comes with
4732 no error message whatsoever. GHC simply fails silently when first invoked,
4733 typically leaving you with this:
4735 make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4736 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4737 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4738 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4739 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4740 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4741 -optc-fomit-frame-pointer -O2 -static
4742 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4743 make[2]: *** [Adjustor.o] Error 1
4744 make[1]: *** [all] Error 1
4745 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4746 make: *** [all] Error 1
4752 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
4753 you'll have to do something more like:
4755 ./configure --with-gcc=...the Cygwin gcc...
4760 <listitem><para> You almost certainly want to set
4764 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
4765 This tells the build system not to split each library into a myriad of little object files, one
4766 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4767 it dramatically increases the time taken to build the libraries in the first place.
4771 <listitem><para> Do not attempt to build the documentation.
4772 It needs all kinds of wierd Jade stuff that we haven't worked out for
4773 Win32.</para></listitem>
projects / ghc-hetmet.git / blob