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 (version 5.x or later) on your machine in
62 order to compile (most of) the sources, however.</para>
67 <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
69 <para>We make releases infrequently. If you want more
70 up-to-the minute (but less tested) source code then you need
71 to get access to our CVS repository.</para>
73 <para>All the <literal>fptools</literal> source code is held
74 in a CVS repository. CVS is a pretty good source-code
75 control system, and best of all it works over the
78 <para>The repository holds source code only. It holds no
79 mechanically generated files at all. So if you check out a
80 source tree from CVS you will need to install every utility
81 so that you can build all the derived files from
84 <para>More information about our CVS repository can be found
85 in <xref linkend="sec-cvs"/>.</para>
90 <para>If you are going to do any building from sources (either
91 from a source distribution or the CVS repository) then you need to
92 read all of this manual in detail.</para>
96 <title>Using the CVS repository</title>
98 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
99 sources for various software projects. CVS lets several people
100 work on the same software at the same time, allowing changes to be
101 checked in incrementally. </para>
103 <para>This section is a set of guidelines for how to use our CVS
104 repository, and will probably evolve in time. The main thing to
105 remember is that most mistakes can be undone, but if there's
106 anything you're not sure about feel free to bug the local CVS
107 meister (namely Jeff Lewis
108 <email>jlewis@galois.com</email>). </para>
110 <sect2 id="cvs-access">
111 <title>Getting access to the CVS Repository</title>
113 <para>You can access the repository in one of two ways:
114 read-only (<xref linkend="cvs-read-only"/>), or read-write (<xref
115 linkend="cvs-read-write"/>).</para>
117 <sect3 id="cvs-read-only">
118 <title>Remote Read-only CVS Access</title>
120 <para>Read-only access is available to anyone - there's no
121 need to ask us first. With read-only CVS access you can do
122 anything except commit changes to the repository. You can
123 make changes to your local tree, and still use CVS's merge
124 facility to keep your tree up to date, and you can generate
125 patches using 'cvs diff' in order to send to us for
128 <para>To get read-only access to the repository:</para>
132 <para>Make sure that <application>cvs</application> is
133 installed on your machine.</para>
136 <para>Set your <literal>$CVSROOT</literal> environment variable to
137 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
138 <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
139 have any trailing spaces on that line, otherwise CVS will respond with
140 a perplexing message like
142 /cvs : no such repository
143 </programlisting></para>
146 <para>Run the command</para>
150 <para>The password is simply <literal>cvs</literal>. This
151 sets up a file in your home directory called
152 <literal>.cvspass</literal>, which squirrels away the
153 dummy password, so you only need to do this step once.</para>
157 <para>Now go to <xref linkend="cvs-first"/>.</para>
162 <sect3 id="cvs-read-write">
163 <title>Remote Read-Write CVS Access</title>
165 <para>We generally supply read-write access to folk doing
166 serious development on some part of the source tree, when
167 going through us would be a pain. If you're developing some
168 feature, or think you have the time and inclination to fix
169 bugs in our sources, feel free to ask for read-write
170 access. There is a certain amount of responsibility that goes
171 with commit privileges; we are more likely to grant you access
172 if you've demonstrated your competence by sending us patches
173 via mail in the past.</para>
175 <para>To get remote read-write CVS access, you need to do the
176 following steps.</para>
180 <para>Make sure that <literal>cvs</literal> and
181 <literal>ssh</literal> are both installed on your
186 <para>Generate a DSA private-key/public-key pair, thus:</para>
190 <para>(<literal>ssh-keygen</literal> comes with
191 <literal>ssh</literal>.) Running <literal>ssh-keygen
192 -d</literal> creates the private and public keys in
193 <literal>$HOME/.ssh/id_dsa</literal> and
194 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
195 (assuming you accept the standard defaults).</para>
197 <para><literal>ssh-keygen -d</literal> will only work if
198 you have Version 2 <literal>ssh</literal> installed; it
199 will fail harmlessly otherwise. If you only have Version
200 1 you can instead generate an RSA key pair using plain</para>
205 <para>Doing so creates the private and public RSA keys in
206 <literal>$HOME/.ssh/identity</literal> and
207 <literal>$HOME/.ssh/identity.pub</literal>
210 <para>[Deprecated.] Incidentally, you can force a Version
211 2 <literal>ssh</literal> to use the Version 1 protocol by
212 creating <literal>$HOME/config</literal> with the
213 following in it:</para>
221 <para>In both cases, <literal>ssh-keygen</literal> will
222 ask for a <firstterm>passphrase</firstterm>. The
223 passphrase is a password that protects your private key.
224 In response to the 'Enter passphrase' question, you can
228 <para>[Recommended.] Enter a passphrase, which you
229 will quote each time you use CVS.
230 <literal>ssh-agent</literal> makes this entirely
234 <para>[Deprecated.] Just hit return (i.e. use an empty
235 passphrase); then you won't need to quote the
236 passphrase when using CVS. The downside is that
237 anyone who can see into your <literal>.ssh</literal>
238 directory, and thereby get your private key, can mess
239 up the repository. So you must keep the
240 <literal>.ssh</literal> directory with draconian
241 no-access permissions.</para>
247 <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
254 <para>Send a message to to the CVS repository
255 administrator (currently Jeff Lewis
256 <email>jeff@galois.com</email>), containing:</para>
259 <para>Your desired user-name.</para>
262 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
263 <literal>.ssh/identity.pub</literal>).</para>
266 <para>He will set up your account.</para>
270 <para>Set the following environment variables:</para>
274 <constant>$HOME</constant>: points to your home directory. This is where CVS
275 will look for its <filename>.cvsrc</filename> file.
281 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
283 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
284 <literal>ssh</literal> assumes that your CVS client
285 understands how to execute shell script
286 ("#!"s,really), which is what
287 <literal>ssh</literal> is. This may not be the case on
288 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
289 <literal>ssh1</literal>.</para>
293 <para><literal>$CVSROOT</literal> to
294 <literal>:ext:</literal><replaceable>your-username</replaceable>
295 <literal>@cvs.haskell.org:/home/cvs/root</literal>
296 where <replaceable>your-username</replaceable> is your user name on
297 <literal>cvs.haskell.org</literal>.
299 <para>The <literal>CVSROOT</literal> environment variable will
300 be recorded in the checked-out tree, so you don't need to set
301 this every time. </para>
307 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
308 if you want to use an Emacs buffer for typing in those long commit messages.
314 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
315 set this to point to <filename>bash.exe</filename>.
326 Put the following in <filename>$HOME/.cvsrc</filename>:
337 These are the default options for the specified CVS commands,
338 and represent better defaults than the usual ones. (Feel
339 free to change them.)
343 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
344 the 8.3 DOS filesystem, but that restriction should have
345 been lifted by now (i.e., you're using VFAT or later filesystems.) If
346 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
354 <para>[Experts.] Once your account is set up, you can get
355 access from other machines without bothering Jeff, thus:</para>
358 <para>Generate a public/private key pair on the new
362 <para>Use ssh to log in to
363 <literal>cvs.haskell.org</literal>, from your old
367 <para>Add the public key for the new machine to the file
368 <literal>$HOME/ssh/authorized_keys</literal> on
369 <literal>cvs.haskell.org</literal>.
370 (<literal>authorized_keys2</literal>, I think, for Version
374 <para>Make sure that the new version of
375 <literal>authorized_keys</literal> still has 600 file
384 <sect2 id="cvs-first">
385 <title>Checking Out a Source Tree</title>
389 <para>Make sure you set your <literal>CVSROOT</literal>
390 environment variable according to either of the remote
391 methods above. The Approved Way to check out a source tree
392 is as follows:</para>
395 $ cvs checkout fpconfig
398 <para>At this point you have a new directory called
399 <literal>fptools</literal> which contains the basic stuff
400 for the fptools suite, including the configuration files and
401 some other junk. </para>
403 <para>[Windows users.] The following messages appear to be harmless:
405 setsockopt IPTOS_LOWDELAY: Invalid argument
406 setsockopt IPTOS_THROUGHPUT: Invalid argument
411 <para>You can call the fptools directory whatever you like,
412 CVS won't mind: </para>
415 $ mv fptools <replaceable>directory</replaceable>
418 <para> NB: after you've read the CVS manual you might be
419 tempted to try</para>
421 $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
424 <para>instead of checking out <literal>fpconfig</literal>
425 and then renaming it. But this doesn't work, and will
426 result in checking out the entire repository instead of just
427 the <literal>fpconfig</literal> bit.</para>
429 $ cd <replaceable>directory</replaceable>
430 $ cvs checkout ghc hslibs libraries
433 <para>The second command here checks out the relevant
434 modules you want to work on. For a GHC build, for instance,
435 you need at least the <literal>ghc</literal>,
436 <literal>hslibs</literal> and <literal>libraries</literal>
437 modules (for a full list of the projects available, see
438 <xref linkend="projects"/>).</para>
440 <para>Remember that if you do not have
441 <literal>happy</literal> and/or <literal>Alex</literal>
442 installed, you need to check them out as well.</para>
447 <sect2 id="cvs-committing">
448 <title>Committing Changes</title>
450 <para>This is only if you have read-write access to the
451 repository. For anoncvs users, CVS will issue a "read-only
452 repository" error if you try to commit changes.</para>
456 <para>Build the software, if necessary. Unless you're just
457 working on documentation, you'll probably want to build the
458 software in order to test any changes you make.</para>
462 <para>Make changes. Preferably small ones first.</para>
466 <para>Test them. You can see exactly what changes you've
467 made by using the <literal>cvs diff</literal> command:</para>
471 <para>lists all the changes (using the
472 <literal>diff</literal> command) in and below the current
473 directory. In emacs, <literal>C-c C-v =</literal> runs
474 <literal>cvs diff</literal> on the current buffer and shows
475 you the results.</para>
479 <para>If you changed something in the
480 <literal>fptools/libraries</literal> subdirectories, also run
481 <literal>make html</literal> to check if the documentation can
482 be generated successfully, too.</para>
486 <para>Before checking in a change, you need to update your
493 <para>This pulls in any changes that other people have made,
494 and merges them with yours. If there are any conflicts, CVS
495 will tell you, and you'll have to resolve them before you
496 can check your changes in. The documentation describes what
497 to do in the event of a conflict.</para>
499 <para>It's not always necessary to do a full cvs update
500 before checking in a change, since CVS will always tell you
501 if you try to check in a file that someone else has changed.
502 However, you should still update at regular intervals to
503 avoid making changes that don't work in conjuction with
504 changes that someone else made. Keeping an eye on what goes
505 by on the mailing list can help here.</para>
509 <para>When you're happy that your change isn't going to
510 break anything, check it in. For a one-file change:</para>
513 $ cvs commit <replaceable>filename</replaceable>
516 <para>CVS will then pop up an editor for you to enter a
517 "commit message", this is just a short description
518 of what your change does, and will be kept in the history of
521 <para>If you're using emacs, simply load up the file into a
522 buffer and type <literal>C-x C-q</literal>, and emacs will
523 prompt for a commit message and then check in the file for
526 <para>For a multiple-file change, things are a bit
527 trickier. There are several ways to do this, but this is the
528 way I find easiest. First type the commit message into a
529 temporary file. Then either</para>
532 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
535 <para>or, if nothing else has changed in this part of the
539 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
542 <para>where <replaceable>directory</replaceable> is a common
543 parent directory for all your changes, and
544 <replaceable>commit-message</replaceable> is the name of the
545 file containing the commit message.</para>
547 <para>Shortly afterwards, you'll get some mail from the
548 relevant mailing list saying which files changed, and giving
549 the commit message. For a multiple-file change, you should
550 still get only <emphasis>one</emphasis> message.</para>
555 <sect2 id="cvs-update">
556 <title>Updating Your Source Tree</title>
558 <para>It can be tempting to cvs update just part of a source
559 tree to bring in some changes that someone else has made, or
560 before committing your own changes. This is NOT RECOMMENDED!
561 Quite often changes in one part of the tree are dependent on
562 changes in another part of the tree (the
563 <literal>mk/*.mk</literal> files are a good example where
564 problems crop up quite often). Having an inconsistent tree is a
565 major cause of headaches. </para>
567 <para>So, to avoid a lot of hassle, follow this recipe for
568 updating your tree:</para>
572 $ cvs update -P 2>&1 | tee log</screen>
574 <para>Look at the log file, and fix any conflicts (denoted by a
575 <quote>C</quote> in the first column). New directories may have
576 appeared in the repository; CVS doesn't check these out by
577 default, so to get new directories you have to explicitly do
579 $ cvs update -d</screen>
580 in each project subdirectory. Don't do this at the top level,
581 because then <emphasis>all</emphasis> the projects will be
584 <para>If you're using multiple build trees, then for every build
585 tree you have pointing at this source tree, you need to update
586 the links in case any new files have appeared: </para>
589 $ cd <replaceable>build-tree</replaceable>
590 $ lndir <replaceable>source-tree</replaceable>
593 <para>Some files might have been removed, so you need to remove
594 the links pointing to these non-existent files:</para>
597 $ find . -xtype l -exec rm '{}' \;
600 <para>To be <emphasis>really</emphasis> safe, you should do
603 <screen>$ gmake all</screen>
605 <para>from the top-level, to update the dependencies and build
606 any changed files. </para>
609 <sect2 id="cvs-tags">
610 <title>GHC Tag Policy</title>
612 <para>If you want to check out a particular version of GHC,
613 you'll need to know how we tag versions in the repository. The
614 policy (as of 4.04) is:</para>
618 <para>The tree is branched before every major release. The
619 branch tag is <literal>ghc-x-xx-branch</literal>, where
620 <literal>x-xx</literal> is the version number of the release
621 with the <literal>'.'</literal> replaced by a
622 <literal>'-'</literal>. For example, the 4.04 release lives
623 on <literal>ghc-4-04-branch</literal>.</para>
627 <para>The release itself is tagged with
628 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
629 called <literal>ghc-4-06</literal>.</para>
633 <para>We didn't always follow these guidelines, so to see
634 what tags there are for previous versions, do <literal>cvs
635 log</literal> on a file that's been around for a while (like
636 <literal>fptools/ghc/README</literal>).</para>
640 <para>So, to check out a fresh GHC 4.06 tree you would
644 $ cvs co -r ghc-4-06 fpconfig
646 $ cvs co -r ghc-4-06 ghc hslibs
650 <sect2 id="cvs-hints">
651 <title>General Hints</title>
655 <para>As a general rule: commit changes in small units,
656 preferably addressing one issue or implementing a single
657 feature. Provide a descriptive log message so that the
658 repository records exactly which changes were required to
659 implement a given feature/fix a bug. I've found this
660 <emphasis>very</emphasis> useful in the past for finding out
661 when a particular bug was introduced: you can just wind back
662 the CVS tree until the bug disappears.</para>
666 <para>Keep the sources at least *buildable* at any given
667 time. No doubt bugs will creep in, but it's quite easy to
668 ensure that any change made at least leaves the tree in a
669 buildable state. We do nightly builds of GHC to keep an eye
670 on what things work/don't work each day and how we're doing
671 in relation to previous verions. This idea is truely wrecked
672 if the compiler won't build in the first place!</para>
676 <para>To check out extra bits into an already-checked-out
677 tree, use the following procedure. Suppose you have a
678 checked-out fptools tree containing just ghc, and you want
679 to add nofib to it:</para>
690 $ cvs update -d nofib
693 <para>(the -d flag tells update to create a new
694 directory). If you just want part of the nofib suite, you
699 $ cvs checkout nofib/spectral
702 <para>This works because <literal>nofib</literal> is a
703 module in its own right, and spectral is a subdirectory of
704 the nofib module. The path argument to checkout must always
705 start with a module name. There's no equivalent form of this
706 command using <literal>update</literal>.</para>
712 <sect1 id="projects">
713 <title>What projects are there?</title>
715 <para>The <literal>fptools</literal> suite consists of several
716 <firstterm>projects</firstterm>, most of which can be downloaded,
717 built and installed individually. Each project corresponds to a
718 subdirectory in the source tree, and if checking out from CVS then
719 each project can be checked out individually by sitting in the top
720 level of your source tree and typing <command>cvs checkout
721 <replaceable>project</replaceable></command>.</para>
723 <para>Here is a list of the projects currently available:</para>
728 <literal>alex</literal>
729 <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
733 url="http://www.haskell.org/alex/">Alex</ulink> lexical
734 analyser generator for Haskell.</para>
740 <literal>ghc</literal>
741 <indexterm><primary><literal>ghc</literal></primary>
742 <secondary>project</secondary></indexterm>
745 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
746 Haskell Compiler</ulink> (minus libraries). Absolutely
747 required for building GHC.</para>
753 <literal>glafp-utils</literal>
754 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
757 <para>Utility programs, some of which are used by the
758 build/installation system. Required for pretty much
765 <literal>greencard</literal>
766 <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
770 url="http://www.haskell.org/greencard/">GreenCard</ulink>
771 system for generating Haskell foreign function
778 <literal>haggis</literal>
779 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
783 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
784 Haskell GUI framework.</para>
790 <literal>haddock</literal>
791 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
795 url="http://www.haskell.org/haddock/">Haddock</ulink>
796 documentation tool.</para>
802 <literal>happy</literal>
803 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
807 url="http://www.haskell.org/happy/">Happy</ulink> Parser
814 <literal>hdirect</literal>
815 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
819 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
820 Haskell interoperability tool.</para>
826 <literal>hood</literal>
827 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
830 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
831 Object Observation Debugger</ulink>.</para>
837 <literal>hslibs</literal>
838 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
841 <para>Supplemental libraries for GHC
842 (<emphasis>required</emphasis> for building GHC).</para>
848 <literal>libraries</literal>
849 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
852 <para>Hierarchical Haskell library suite
853 (<emphasis>required</emphasis> for building GHC).</para>
859 <literal>mhms</literal>
860 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
863 <para>The Modular Haskell Metric System.</para>
869 <literal>nofib</literal>
870 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
873 <para>The NoFib suite: A collection of Haskell programs used
874 primarily for benchmarking.</para>
880 <literal>testsuite</literal>
881 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
884 <para>A testing framework, including GHC's regression test
890 <para>So, to build GHC you need at least the
891 <literal>ghc</literal>, <literal>libraries</literal> and
892 <literal>hslibs</literal> projects (a GHC source distribution will
893 already include the bits you need).</para>
896 <sect1 id="sec-build-checks">
897 <title>Things to check before you start</title>
899 <para>Here's a list of things to check before you get
904 <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
905 space needed: from about 100Mb for a basic GHC
906 build, up to probably 500Mb for a GHC build with everything
907 included (libraries built several different ways,
912 <para>Use an appropriate machine / operating system. <xref
913 linkend="sec-port-info"/> lists the supported platforms; if
914 yours isn't amongst these then you can try porting GHC (see
915 <xref linkend="sec-porting-ghc"/>).</para>
919 <para>Be sure that the “pre-supposed” utilities are
920 installed. <xref linkend="sec-pre-supposed"/>
925 <para>If you have any problem when building or installing the
926 Glasgow tools, please check the “known pitfalls” (<xref
927 linkend="sec-build-pitfalls"/>). Also check the FAQ for the
928 version you're building, which is part of the User's Guide and
929 available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
932 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
934 <para>If you feel there is still some shortcoming in our
935 procedure or instructions, please report it.</para>
937 <para>For GHC, please see the <ulink
938 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
939 section of the GHC Users' Guide</ulink>, to maximise the
940 usefulness of your report.</para>
942 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
943 <para>If in doubt, please send a message to
944 <email>glasgow-haskell-bugs@haskell.org</email>.
945 <indexterm><primary>bugs</primary><secondary>mailing
946 list</secondary></indexterm></para>
951 <sect1 id="sec-port-info">
952 <title>What machines the Glasgow tools run on</title>
954 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
955 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
956 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
958 <para>The main question is whether or not the Haskell compiler
959 (GHC) runs on your platform.</para>
961 <para>A “platform” is a
962 architecture/manufacturer/operating-system combination, such as
963 <literal>sparc-sun-solaris2</literal>. Other common ones are
964 <literal>alpha-dec-osf2</literal>,
965 <literal>hppa1.1-hp-hpux9</literal>,
966 <literal>i386-unknown-linux</literal>,
967 <literal>i386-unknown-solaris2</literal>,
968 <literal>i386-unknown-freebsd</literal>,
969 <literal>i386-unknown-cygwin32</literal>,
970 <literal>m68k-sun-sunos4</literal>,
971 <literal>mips-sgi-irix5</literal>,
972 <literal>sparc-sun-sunos4</literal>,
973 <literal>sparc-sun-solaris2</literal>,
974 <literal>powerpc-ibm-aix</literal>.</para>
976 <para>Some libraries may only work on a limited number of
977 platforms; for example, a sockets library is of no use unless the
978 operating system supports the underlying BSDisms.</para>
981 <title>What platforms the Haskell compiler (GHC) runs on</title>
983 <indexterm><primary>fully-supported platforms</primary></indexterm>
984 <indexterm><primary>native-code generator</primary></indexterm>
985 <indexterm><primary>registerised ports</primary></indexterm>
986 <indexterm><primary>unregisterised ports</primary></indexterm>
988 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
989 native-code generator; (b) next best is a
990 “registerised” port; (c) the bare minimum is an
991 “unregisterised” port.
992 (“Unregisterised” is so terrible that we won't say
993 more about it).</para>
995 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
996 FreeBSD and Linux, so those are the best supported platforms,
997 unsurprisingly.</para>
999 <para>Here's everything that's known about GHC ports. We
1000 identify platforms by their “canonical”
1001 CPU/Manufacturer/OS triple.</para>
1005 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
1006 <indexterm><primary>alpha-dec-osf</primary></indexterm>
1007 <indexterm><primary>alpha-dec-linux</primary></indexterm>
1008 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
1009 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
1010 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
1013 <para>The OSF port is currently working (as of GHC version
1014 5.02.1) and well supported. The native code generator is
1015 currently non-working. Other operating systems will
1016 require some minor porting.</para>
1021 <term>sparc-sun-sunos4
1022 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
1025 <para>Probably works with minor tweaks, hasn't been tested
1031 <term>sparc-sun-solaris2
1032 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
1035 <para>Fully supported (at least for Solaris 2.7 and 2.6),
1036 including native-code generator.</para>
1041 <term>sparc-unknown-openbsd
1042 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
1045 <para>Supported, including native-code generator. The
1046 same should also be true of NetBSD</para>
1051 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
1052 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1055 <para>A registerised port is available for version 4.08,
1056 but GHC hasn't been built on that platform since (as far
1057 as we know). No native-code generator.</para>
1062 <term>i386-unknown-linux (PCs running Linux, ELF binary format)
1063 <indexterm><primary>i386-*-linux</primary></indexterm>
1066 <para>GHC works registerised and has a native code
1067 generator. You <emphasis>must</emphasis> have GCC 2.7.x
1068 or later. NOTE about <literal>glibc</literal> versions:
1069 GHC binaries built on a system running <literal>glibc
1070 2.0</literal> won't work on a system running
1071 <literal>glibc 2.1</literal>, and vice versa. In general,
1072 don't expect compatibility between
1073 <literal>glibc</literal> versions, even if the shared
1074 library version hasn't changed.</para>
1079 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
1080 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1083 <para>GHC works registerised. Pre-built packages are
1084 available in the native package format, so if you just
1085 need binaries you're better off just installing the
1086 package (it might even be on your installation
1092 <term>i386-unknown-openbsd (PCs running OpenBSD)
1093 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1096 <para>Supported, with native code generator. Packages are
1097 available through the ports system in the native package
1103 <term>i386-unknown-netbsd (PCs running NetBSD)
1104 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1107 <para>Will require some minor porting effort, but should
1108 work registerised.</para>
1113 <term>i386-unknown-mingw32 (PCs running Windows)
1114 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1117 <para>Fully supported under Win9x, WinNT, Win2k, and
1118 WinXP. Includes a native code generator. Building from
1119 source requires a recent <ulink
1120 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1121 to be installed.</para>
1126 <term>ia64-unknown-linux
1127 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1130 <para>Supported, except there is no native code
1136 <term>x86_64-unknown-linux
1137 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1140 <para>GHC currently works unregisterised. A registerised
1141 port is in progress.</para>
1146 <term>amd64-unknown-openbsd
1147 <indexterm><primary>amd64-unknown-linux</primary></indexterm>
1150 <para>(This is the same as x86_64-unknown-openbsd). GHC
1151 currently works unregisterised. A registerised port is in
1157 <term>mips-sgi-irix5
1158 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1161 <para>Port has worked in the past, but hasn't been tested
1162 for some time (and will certainly have rotted in various
1163 ways). As usual, we don't have access to machines and
1164 there hasn't been an overwhelming demand for this port,
1165 but feel free to get in touch.</para>
1170 <term>mips64-sgi-irix6
1171 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
1174 <para>GHC currently works unregisterised.</para>
1179 <term>powerpc-ibm-aix
1180 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1183 <para>Port currently doesn't work, needs some minimal
1184 porting effort. As usual, we don't have access to
1185 machines and there hasn't been an overwhelming demand for
1186 this port, but feel free to get in touch.</para>
1191 <term>powerpc-apple-darwin
1192 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1195 <para>Supported registerised. Native code generator is
1196 almost working.</para>
1201 <term>powerpc-apple-linux
1202 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1205 <para>Not supported (yet).</para>
1210 <para>Various other systems have had GHC ported to them in the
1211 distant past, including various Motorola 68k boxes. The 68k
1212 support still remains, but porting to one of these systems will
1213 certainly be a non-trivial task.</para>
1217 <title>What machines the other tools run on</title>
1219 <para>Unless you hear otherwise, the other tools work if GHC
1225 <sect1 id="sec-pre-supposed">
1226 <title>Installing pre-supposed utilities</title>
1228 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1229 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1231 <para>Here are the gory details about some utility programs you
1232 may need; <command>perl</command>, <command>gcc</command> and
1233 <command>happy</command> are the only important
1234 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1235 important if you're going for Parallel Haskell.) The
1236 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1237 script will tell you if you are missing something.</para>
1243 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1244 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1247 <para>GHC is required to build many of the tools, including
1248 GHC itself. If you need to port GHC to your platform
1249 because there isn't a binary distribution of GHC available,
1250 then see <xref linkend="sec-porting-ghc"/>.</para>
1252 <para>Which version of GHC you need will depend on the
1253 packages you intend to build. GHC itself will normally
1254 build using one of several older versions of itself - check
1255 the announcement or release notes for details.</para>
1261 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1262 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1265 <para><emphasis>You have to have Perl to proceed!</emphasis>
1266 Perl version 5 at least is required. GHC has been known to
1267 tickle bugs in Perl, so if you find that Perl crashes when
1268 running GHC try updating (or downgrading) your Perl
1269 installation. Versions of Perl that we use and are known to
1270 be fairly stable are 5.005 and 5.6.1.</para>
1272 <para>For Win32 platforms, you should use the binary
1273 supplied in the InstallShield (copy it to
1274 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1277 <para>Perl should be put somewhere so that it can be invoked
1278 by the <literal>#!</literal> script-invoking
1279 mechanism. The full pathname may need to be less than 32
1280 characters long on some systems.</para>
1285 <term>GNU C (<command>gcc</command>)
1286 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
1287 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
1290 <para>We recommend using GCC version 2.95.2 on all
1291 platforms. Failing that, version 2.7.2 is stable on most
1292 platforms. Earlier versions of GCC can be assumed not to
1293 work, and versions in between 2.7.2 and 2.95.2 (including
1294 <command>egcs</command>) have varying degrees of stability
1295 depending on the platform.</para>
1297 <para>GCC 3.2 is currently known to have problems building
1298 GHC on Sparc, but is stable on x86.</para>
1300 <para>If your GCC dies with “internal error” on
1301 some GHC source file, please let us know, so we can report
1302 it and get things improved. (Exception: on x86
1303 boxes—you may need to fiddle with GHC's
1304 <option>-monly-N-regs</option> option; see the User's
1311 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
1314 <para>The fptools build system makes heavy use of features
1315 specific to GNU <command>make</command>, so you must have
1316 this installed in order to build any of the fptools
1323 <indexterm><primary>Happy</primary></indexterm>
1326 <para>Happy is a parser generator tool for Haskell, and is
1327 used to generate GHC's parsers. Happy is written in
1328 Haskell, and is a project in the CVS repository
1329 (<literal>fptools/happy</literal>). It can be built from
1330 source, but bear in mind that you'll need GHC installed in
1331 order to build it. To avoid the chicken/egg problem,
1332 install a binary distribution of either Happy or GHC to get
1333 started. Happy distributions are available from <ulink
1334 url="http://www.haskell.org/happy/">Happy's Web
1335 Page</ulink>.</para>
1341 <indexterm><primary>Alex</primary></indexterm>
1344 <para>Alex is a lexical-analyser generator for Haskell,
1345 which GHC uses to generate its lexer. Like Happy, Alex is
1346 written in Haskell and is a project in the CVS repository.
1347 Alex distributions are available from <ulink
1348 url="http://www.haskell.org/alex/">Alex's Web
1349 Page</ulink>.</para>
1355 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
1356 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
1359 <para>GNU autoconf is needed if you intend to build from the
1360 CVS sources, it is <emphasis>not</emphasis> needed if you
1361 just intend to build a standard source distribution.</para>
1363 <para>Version 2.52 or later of the autoconf package is required.
1364 NB. version 2.13 will no longer work, as of GHC version
1367 <para><command>autoreconf</command> (from the autoconf package)
1368 recursively builds <command>configure</command> scripts from
1369 the corresponding <filename>configure.ac</filename> and
1370 <filename>aclocal.m4</filename> files. If you modify one of
1371 the latter files, you'll need <command>autoreconf</command> to
1372 rebuild the corresponding <filename>configure</filename>.</para>
1377 <term><command>sed</command>
1378 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1379 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1382 <para>You need a working <command>sed</command> if you are
1383 going to build from sources. The build-configuration stuff
1384 needs it. GNU sed version 2.0.4 is no good! It has a bug
1385 in it that is tickled by the build-configuration. 2.0.5 is
1386 OK. Others are probably OK too (assuming we don't create too
1387 elaborate configure scripts.)</para>
1392 <para>One <literal>fptools</literal> project is worth a quick note
1393 at this point, because it is useful for all the others:
1394 <literal>glafp-utils</literal> contains several utilities which
1395 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1396 Like <command>lndir</command> for creating symbolic link
1399 <sect2 id="pre-supposed-gph-tools">
1400 <title>Tools for building parallel GHC (GPH)</title>
1404 <term>PVM version 3:
1405 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1406 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1409 <para>PVM is the Parallel Virtual Machine on which
1410 Parallel Haskell programs run. (You only need this if you
1411 plan to run Parallel Haskell. Concurrent Haskell, which
1412 runs concurrent threads on a uniprocessor doesn't need
1413 it.) Underneath PVM, you can have (for example) a network
1414 of workstations (slow) or a multiprocessor box
1417 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1418 It is readily available on the net; I think I got it from
1419 <literal>research.att.com</literal>, in
1420 <filename>netlib</filename>.</para>
1422 <para>A PVM installation is slightly quirky, but easy to
1423 do. Just follow the <filename>Readme</filename>
1424 instructions.</para>
1429 <term><command>bash</command>:
1430 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1433 <para>Sadly, the <command>gr2ps</command> script, used to
1434 convert “parallelism profiles” to PostScript,
1435 is written in Bash (GNU's Bourne Again shell). This bug
1436 will be fixed (someday).</para>
1442 <sect2 id="pre-supposed-other-tools">
1443 <title>Other useful tools</title>
1448 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1449 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1452 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1453 to build a couple of utilities in
1454 <literal>glafp-utils</literal>. Depending on your
1455 operating system, the supplied <command>lex</command> may
1456 or may not work; you should get the GNU version.</para>
1461 <para>More tools are required if you want to format the documentation
1462 that comes with GHC and other fptools projects. See <xref
1463 linkend="building-docs"/>.</para>
1467 <sect1 id="sec-building-from-source">
1468 <title>Building from source</title>
1470 <indexterm><primary>Building from source</primary></indexterm>
1471 <indexterm><primary>Source, building from</primary></indexterm>
1473 <para>You've been rash enough to want to build some of the Glasgow
1474 Functional Programming tools (GHC, Happy, nofib, etc.) from
1475 source. You've slurped the source, from the CVS repository or
1476 from a source distribution, and now you're sitting looking at a
1477 huge mound of bits, wondering what to do next.</para>
1479 <para>Gingerly, you type <command>make</command>. Wrong
1482 <para>This rest of this guide is intended for duffers like me, who
1483 aren't really interested in Makefiles and systems configurations,
1484 but who need a mental model of the interlocking pieces so that
1485 they can make them work, extend them consistently when adding new
1486 software, and lay hands on them gently when they don't
1489 <sect2 id="quick-start">
1490 <title>Quick Start</title>
1492 <para>If you are starting from a source distribution, and just
1493 want a completely standard build, then the following should
1496 <screen>$ autoreconf
1502 <para>For GHC, this will do a 2-stage bootstrap build of the
1503 compiler, with profiling libraries, and install the
1506 <para>If you want to do anything at all non-standard, or you
1507 want to do some development, read on...</para>
1510 <sect2 id="sec-source-tree">
1511 <title>Your source tree</title>
1513 <para>The source code is held in your <emphasis>source
1514 tree</emphasis>. The root directory of your source tree
1515 <emphasis>must</emphasis> contain the following directories and
1520 <para><filename>Makefile</filename>: the root
1525 <para><filename>mk/</filename>: the directory that contains
1526 the main Makefile code, shared by all the
1527 <literal>fptools</literal> software.</para>
1531 <para><filename>configure.ac</filename>,
1532 <filename>config.sub</filename>,
1533 <filename>config.guess</filename>: these files support the
1534 configuration process.</para>
1538 <para><filename>install-sh</filename>.</para>
1542 <para>All the other directories are individual
1543 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1544 system—for example, the Glasgow Haskell Compiler
1545 (<literal>ghc</literal>), the Happy parser generator
1546 (<literal>happy</literal>), the <literal>nofib</literal>
1547 benchmark suite, and so on. You can have zero or more of these.
1548 Needless to say, some of them are needed to build others.</para>
1550 <para>The important thing to remember is that even if you want
1551 only one project (<literal>happy</literal>, say), you must have
1552 a source tree whose root directory contains
1553 <filename>Makefile</filename>, <filename>mk/</filename>,
1554 <filename>configure.ac</filename>, and the project(s) you want
1555 (<filename>happy/</filename> in this case). You cannot get by
1556 with just the <filename>happy/</filename> directory.</para>
1560 <title>Build trees</title>
1561 <indexterm><primary>build trees</primary></indexterm>
1562 <indexterm><primary>link trees, for building</primary></indexterm>
1564 <para>If you just want to build the software once on a single
1565 platform, then your source tree can also be your build tree, and
1566 you can skip the rest of this section.</para>
1568 <para>We often want to build multiple versions of our software
1569 for different architectures, or with different options
1570 (e.g. profiling). It's very desirable to share a single copy of
1571 the source code among all these builds.</para>
1573 <para>So for every source tree we have zero or more
1574 <emphasis>build trees</emphasis>. Each build tree is initially
1575 an exact copy of the source tree, except that each file is a
1576 symbolic link to the source file, rather than being a copy of
1577 the source file. There are “standard” Unix
1578 utilities that make such copies, so standard that they go by
1580 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1581 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1582 are two (If you don't have either, the source distribution
1583 includes sources for the X11
1584 <command>lndir</command>—check out
1585 <filename>fptools/glafp-utils/lndir</filename>). See <xref
1586 linkend="sec-storysofar"/> for a typical invocation.</para>
1588 <para>The build tree does not need to be anywhere near the
1589 source tree in the file system. Indeed, one advantage of
1590 separating the build tree from the source is that the build tree
1591 can be placed in a non-backed-up partition, saving your systems
1592 support people from backing up untold megabytes of
1593 easily-regenerated, and rapidly-changing, gubbins. The golden
1594 rule is that (with a single exception—<xref
1595 linkend="sec-build-config"/>) <emphasis>absolutely everything in
1596 the build tree is either a symbolic link to the source tree, or
1597 else is mechanically generated</emphasis>. It should be
1598 perfectly OK for your build tree to vanish overnight; an hour or
1599 two compiling and you're on the road again.</para>
1601 <para>You need to be a bit careful, though, that any new files
1602 you create (if you do any development work) are in the source
1603 tree, not a build tree!</para>
1605 <para>Remember, that the source files in the build tree are
1606 <emphasis>symbolic links</emphasis> to the files in the source
1607 tree. (The build tree soon accumulates lots of built files like
1608 <filename>Foo.o</filename>, as well.) You can
1609 <emphasis>delete</emphasis> a source file from the build tree
1610 without affecting the source tree (though it's an odd thing to
1611 do). On the other hand, if you <emphasis>edit</emphasis> a
1612 source file from the build tree, you'll edit the source-tree
1613 file directly. (You can set up Emacs so that if you edit a
1614 source file from the build tree, Emacs will silently create an
1615 edited copy of the source file in the build tree, leaving the
1616 source file unchanged; but the danger is that you think you've
1617 edited the source file whereas actually all you've done is edit
1618 the build-tree copy. More commonly you do want to edit the
1619 source file.)</para>
1621 <para>Like the source tree, the top level of your build tree
1622 must be (a linked copy of) the root directory of the
1623 <literal>fptools</literal> suite. Inside Makefiles, the root of
1624 your build tree is called
1625 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1626 In the rest of this document path names are relative to
1627 <constant>$(FPTOOLS_TOP)</constant> unless
1628 otherwise stated. For example, the file
1629 <filename>ghc/mk/target.mk</filename> is actually
1630 <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
1633 <sect2 id="sec-build-config">
1634 <title>Getting the build you want</title>
1636 <para>When you build <literal>fptools</literal> you will be
1637 compiling code on a particular <emphasis>host
1638 platform</emphasis>, to run on a particular <emphasis>target
1639 platform</emphasis> (usually the same as the host
1640 platform)<indexterm><primary>platform</primary></indexterm>.
1641 The difficulty is that there are minor differences between
1642 different platforms; minor, but enough that the code needs to be
1643 a bit different for each. There are some big differences too:
1644 for a different architecture we need to build GHC with a
1645 different native-code generator.</para>
1647 <para>There are also knobs you can turn to control how the
1648 <literal>fptools</literal> software is built. For example, you
1649 might want to build GHC optimised (so that it runs fast) or
1650 unoptimised (so that you can compile it fast after you've
1651 modified it. Or, you might want to compile it with debugging on
1652 (so that extra consistency-checking code gets included) or off.
1655 <para>All of this stuff is called the
1656 <emphasis>configuration</emphasis> of your build. You set the
1657 configuration using a three-step process.</para>
1661 <term>Step 1: get ready for configuration.</term>
1663 <para>NOTE: if you're starting from a source distribution,
1664 rather than CVS sources, you can skip this step.</para>
1666 <para>Change directory to
1667 <constant>$(FPTOOLS_TOP)</constant> and
1668 issue the command</para>
1672 <indexterm><primary>autoreconf</primary></indexterm>
1673 <para>(with no arguments). This GNU program (recursively) converts
1674 <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
1675 <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
1676 to a shell script called
1677 <filename>$(FPTOOLS_TOP)/configure</filename>.
1678 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
1679 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
1680 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
1681 a message like "No rule to make target 'mk/config.h.in'".
1684 <para>Some projects, including GHC, have their own configure script.
1685 <command>autoreconf</command> takes care of that, too, so all you have
1686 to do is calling <command>autoreconf</command> in the top-level directory
1687 <filename>$(FPTOOLS_TOP)</filename>.</para>
1689 <para>These steps are completely platform-independent; they just mean
1690 that the human-written files (<filename>configure.ac</filename> and
1691 <filename>aclocal.m4</filename>) can be short, although the resulting
1692 files (the <command>configure</command> shell scripts and the C header
1693 template <filename>mk/config.h.in</filename>) are long.</para>
1698 <term>Step 2: system configuration.</term>
1700 <para>Runs the newly-created <command>configure</command>
1701 script, thus:</para>
1704 ./configure <optional><parameter>args</parameter></optional>
1707 <para><command>configure</command>'s mission is to scurry
1708 round your computer working out what architecture it has,
1709 what operating system, whether it has the
1710 <function>vfork</function> system call, where
1711 <command>tar</command> is kept, whether
1712 <command>gcc</command> is available, where various obscure
1713 <literal>#include</literal> files are, whether it's a
1714 leap year, and what the systems manager had for lunch. It
1715 communicates these snippets of information in two
1722 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1724 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1725 substituting for things between
1726 “<literal>@</literal>” brackets. So,
1727 “<literal>@HaveGcc@</literal>” will be
1728 replaced by “<literal>YES</literal>” or
1729 “<literal>NO</literal>” depending on what
1730 <command>configure</command> finds.
1731 <filename>mk/config.mk</filename> is included by every
1732 Makefile (directly or indirectly), so the
1733 configuration information is thereby communicated to
1734 all Makefiles.</para>
1738 <para> It translates
1739 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1741 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1742 The latter is <literal>#include</literal>d by
1743 various C programs, which can thereby make use of
1744 configuration information.</para>
1748 <para><command>configure</command> takes some optional
1749 arguments. Use <literal>./configure --help</literal> to
1750 get a list of the available arguments. Here are some of
1751 the ones you might need:</para>
1755 <term><literal>--with-ghc=<parameter>path</parameter></literal>
1756 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
1759 <para>Specifies the path to an installed GHC which
1760 you would like to use. This compiler will be used
1761 for compiling GHC-specific code (eg. GHC itself).
1762 This option <emphasis>cannot</emphasis> be specified
1763 using <filename>build.mk</filename> (see later),
1764 because <command>configure</command> needs to
1765 auto-detect the version of GHC you're using. The
1766 default is to look for a compiler named
1767 <literal>ghc</literal> in your path.</para>
1772 <term><literal>--with-hc=<parameter>path</parameter></literal>
1773 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
1776 <para>Specifies the path to any installed Haskell
1777 compiler. This compiler will be used for compiling
1778 generic Haskell code. The default is to use
1779 <literal>ghc</literal>.</para>
1784 <term><literal>--with-gcc=<parameter>path</parameter></literal>
1785 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
1788 <para>Specifies the path to the installed GCC. This
1789 compiler will be used to compile all C files,
1790 <emphasis>except</emphasis> any generated by the
1791 installed Haskell compiler, which will have its own
1792 idea of which C compiler (if any) to use. The
1793 default is to use <literal>gcc</literal>.</para>
1801 <term>Step 3: build configuration.</term>
1803 <para>Next, you say how this build of
1804 <literal>fptools</literal> is to differ from the standard
1805 defaults by creating a new file
1806 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1807 <emphasis>in the build tree</emphasis>. This file is the
1808 one and only file you edit in the build tree, precisely
1809 because it says how this build differs from the source.
1810 (Just in case your build tree does die, you might want to
1811 keep a private directory of <filename>build.mk</filename>
1812 files, and use a symbolic link in each build tree to point
1813 to the appropriate one.) So
1814 <filename>mk/build.mk</filename> never exists in the
1815 source tree—you create one in each build tree from
1816 the template. We'll discuss what to put in it
1822 <para>And that's it for configuration. Simple, eh?</para>
1824 <para>What do you put in your build-specific configuration file
1825 <filename>mk/build.mk</filename>? <emphasis>For almost all
1826 purposes all you will do is put make variable definitions that
1827 override those in</emphasis>
1828 <filename>mk/config.mk.in</filename>. The whole point of
1829 <filename>mk/config.mk.in</filename>—and its derived
1830 counterpart <filename>mk/config.mk</filename>—is to define
1831 the build configuration. It is heavily commented, as you will
1832 see if you look at it. So generally, what you do is look at
1833 <filename>mk/config.mk.in</filename>, and add definitions in
1834 <filename>mk/build.mk</filename> that override any of the
1835 <filename>config.mk</filename> definitions that you want to
1836 change. (The override occurs because the main boilerplate file,
1837 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1838 includes <filename>build.mk</filename> after
1839 <filename>config.mk</filename>.)</para>
1841 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1842 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1844 <para>For example, <filename>config.mk.in</filename> contains
1845 the definition:</para>
1848 GhcHcOpts=-O -Rghc-timing
1851 <para>The accompanying comment explains that this is the list of
1852 flags passed to GHC when building GHC itself. For doing
1853 development, it is wise to add <literal>-DDEBUG</literal>, to
1854 enable debugging code. So you would add the following to
1855 <filename>build.mk</filename>:</para>
1857 <para>or, if you prefer,</para>
1860 GhcHcOpts += -DDEBUG
1863 <para>GNU <command>make</command> allows existing definitions to
1864 have new text appended using the “<literal>+=</literal>”
1865 operator, which is quite a convenient feature.)</para>
1867 <para>If you want to remove the <literal>-O</literal> as well (a
1868 good idea when developing, because the turn-around cycle gets a
1869 lot quicker), you can just override
1870 <literal>GhcLibHcOpts</literal> altogether:</para>
1873 GhcHcOpts=-DDEBUG -Rghc-timing
1876 <para>When reading <filename>config.mk.in</filename>, remember
1877 that anything between “@...@” signs is going to be substituted
1878 by <command>configure</command> later. You
1879 <emphasis>can</emphasis> override the resulting definition if
1880 you want, but you need to be a bit surer what you are doing.
1881 For example, there's a line that says:</para>
1887 <para>This defines the Make variables <constant>TAR</constant>
1888 to the pathname for a <command>tar</command> that
1889 <command>configure</command> finds somewhere. If you have your
1890 own pet <command>tar</command> you want to use instead, that's
1891 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1897 <para>You do not <emphasis>have</emphasis> to have a
1898 <filename>mk/build.mk</filename> file at all; if you don't,
1899 you'll get all the default settings from
1900 <filename>mk/config.mk.in</filename>.</para>
1902 <para>You can also use <filename>build.mk</filename> to override
1903 anything that <command>configure</command> got wrong. One place
1904 where this happens often is with the definition of
1905 <constant>FPTOOLS_TOP_ABS</constant>: this
1906 variable is supposed to be the canonical path to the top of your
1907 source tree, but if your system uses an automounter then the
1908 correct directory is hard to find automatically. If you find
1909 that <command>configure</command> has got it wrong, just put the
1910 correct definition in <filename>build.mk</filename>.</para>
1914 <sect2 id="sec-storysofar">
1915 <title>The story so far</title>
1917 <para>Let's summarise the steps you need to carry to get
1918 yourself a fully-configured build tree from scratch.</para>
1922 <para> Get your source tree from somewhere (CVS repository
1923 or source distribution). Say you call the root directory
1924 <filename>myfptools</filename> (it does not have to be
1925 called <filename>fptools</filename>). Make sure that you
1926 have the essential files (see <xref
1927 linkend="sec-source-tree"/>).</para>
1932 <para>(Optional) Use <command>lndir</command> or
1933 <command>mkshadowdir</command> to create a build tree.</para>
1937 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1940 <para>(N.B. <command>mkshadowdir</command>'s first argument
1941 is taken relative to its second.) You probably want to give
1942 the build tree a name that suggests its main defining
1943 characteristic (in your mind at least), in case you later
1948 <para>Change directory to the build tree. Everything is
1949 going to happen there now.</para>
1952 $ cd /scratch/joe-bloggs/myfptools-sun4
1958 <para>Prepare for system configuration:</para>
1964 <para>(You can skip this step if you are starting from a
1965 source distribution, and you already have
1966 <filename>configure</filename> and
1967 <filename>mk/config.h.in</filename>.)</para>
1971 <para>Do system configuration:</para>
1977 <para>Don't forget to check whether you need to add any
1978 arguments to <literal>configure</literal>; for example, a
1979 common requirement is to specify which GHC to use with
1980 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1984 <para>Create the file <filename>mk/build.mk</filename>,
1985 adding definitions for your desired configuration
1994 <para>You can make subsequent changes to
1995 <filename>mk/build.mk</filename> as often as you like. You do
1996 not have to run any further configuration programs to make these
1997 changes take effect. In theory you should, however, say
1998 <command>gmake clean</command>, <command>gmake all</command>,
1999 because configuration option changes could affect
2000 anything—but in practice you are likely to know what's
2005 <title>Making things</title>
2007 <para>At this point you have made yourself a fully-configured
2008 build tree, so you are ready to start building real
2011 <para>The first thing you need to know is that <emphasis>you
2012 must use GNU <command>make</command>, usually called
2013 <command>gmake</command>, not standard Unix
2014 <command>make</command></emphasis>. If you use standard Unix
2015 <command>make</command> you will get all sorts of error messages
2016 (but no damage) because the <literal>fptools</literal>
2017 <command>Makefiles</command> use GNU <command>make</command>'s
2018 facilities extensively.</para>
2020 <para>To just build the whole thing, <command>cd</command> to
2021 the top of your <literal>fptools</literal> tree and type
2022 <command>gmake</command>. This will prepare the tree and build
2023 the various projects in the correct order.</para>
2026 <sect2 id="sec-bootstrapping">
2027 <title>Bootstrapping GHC</title>
2029 <para>GHC requires a 2-stage bootstrap in order to provide
2030 full functionality, including GHCi. By a 2-stage bootstrap, we
2031 mean that the compiler is built once using the installed GHC,
2032 and then again using the compiler built in the first stage. You
2033 can also build a stage 3 compiler, but this normally isn't
2034 necessary except to verify that the stage 2 compiler is working
2037 <para>Note that when doing a bootstrap, the stage 1 compiler
2038 must be built, followed by the runtime system and libraries, and
2039 then the stage 2 compiler. The correct ordering is implemented
2040 by the top-level fptools <filename>Makefile</filename>, so if
2041 you want everything to work automatically it's best to start
2042 <command>make</command> from the top of the tree. When building
2043 GHC, the top-level fptools <filename>Makefile</filename> is set
2044 up to do a 2-stage bootstrap by default (when you say
2045 <command>make</command>). Some other targets it supports
2052 <para>Build everything as normal, including the stage 1
2060 <para>Build the stage 2 compiler only.</para>
2067 <para>Build the stage 3 compiler only.</para>
2072 <term>bootstrap</term> <term>bootstrap2</term>
2074 <para>Build stage 1 followed by stage 2.</para>
2079 <term>bootstrap3</term>
2081 <para>Build stages 1, 2 and 3.</para>
2086 <term>install</term>
2088 <para>Install everything, including the compiler built in
2089 stage 2. To override the stage, say <literal>make install
2090 stage=<replaceable>n</replaceable></literal> where
2091 <replaceable>n</replaceable> is the stage to install.</para>
2096 <para>The top-level <filename>Makefile</filename> also arranges
2097 to do the appropriate <literal>make boot</literal> steps (see
2098 below) before actually building anything.</para>
2100 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2101 and <literal>stage3</literal> targets also work in the
2102 <literal>ghc/compiler</literal> directory, but don't forget that
2103 each stage requires its own <literal>make boot</literal> step:
2104 for example, you must do</para>
2106 <screen>$ make boot stage=2</screen>
2108 <para>before <literal>make stage2</literal> in
2109 <literal>ghc/compiler</literal>.</para>
2112 <sect2 id="sec-standard-targets">
2113 <title>Standard Targets</title>
2114 <indexterm><primary>targets, standard makefile</primary></indexterm>
2115 <indexterm><primary>makefile targets</primary></indexterm>
2117 <para>In any directory you should be able to make the following:</para>
2121 <term><literal>boot</literal></term>
2123 <para>does the one-off preparation required to get ready
2124 for the real work. Notably, it does <command>gmake
2125 depend</command> in all directories that contain programs.
2126 It also builds the necessary tools for compilation to
2129 <para>Invoking the <literal>boot</literal> target
2130 explicitly is not normally necessary. From the top-level
2131 <literal>fptools</literal> directory, invoking
2132 <literal>gmake</literal> causes <literal>gmake boot
2133 all</literal> to be invoked in each of the project
2134 subdirectories, in the order specified by
2135 <literal>$(AllTargets)</literal> in
2136 <literal>config.mk</literal>.</para>
2138 <para>If you're working in a subdirectory somewhere and
2139 need to update the dependencies, <literal>gmake
2140 boot</literal> is a good way to do it.</para>
2145 <term><literal>all</literal></term>
2147 <para>makes all the final target(s) for this Makefile.
2148 Depending on which directory you are in a “final
2149 target” may be an executable program, a library
2150 archive, a shell script, or a Postscript file. Typing
2151 <command>gmake</command> alone is generally the same as
2152 typing <command>gmake all</command>.</para>
2157 <term><literal>install</literal></term>
2159 <para>installs the things built by <literal>all</literal>
2160 (except for the documentation). Where does it install
2161 them? That is specified by
2162 <filename>mk/config.mk.in</filename>; you can override it
2163 in <filename>mk/build.mk</filename>, or by running
2164 <command>configure</command> with command-line arguments
2165 like <literal>--bindir=/home/simonpj/bin</literal>; see
2166 <literal>./configure --help</literal> for the full
2172 <term><literal>install-docs</literal></term>
2174 <para>installs the documentation. Otherwise behaves just
2175 like <literal>install</literal>.</para>
2180 <term><literal>uninstall</literal></term>
2182 <para>reverses the effect of
2183 <literal>install</literal>.</para>
2188 <term><literal>clean</literal></term>
2190 <para>Delete all files from the current directory that are
2191 normally created by building the program. Don't delete
2192 the files that record the configuration, or files
2193 generated by <command>gmake boot</command>. Also preserve
2194 files that could be made by building, but normally aren't
2195 because the distribution comes with them.</para>
2200 <term><literal>distclean</literal></term>
2202 <para>Delete all files from the current directory that are
2203 created by configuring or building the program. If you
2204 have unpacked the source and built the program without
2205 creating any other files, <literal>make
2206 distclean</literal> should leave only the files that were
2207 in the distribution.</para>
2212 <term><literal>mostlyclean</literal></term>
2214 <para>Like <literal>clean</literal>, but may refrain from
2215 deleting a few files that people normally don't want to
2221 <term><literal>maintainer-clean</literal></term>
2223 <para>Delete everything from the current directory that
2224 can be reconstructed with this Makefile. This typically
2225 includes everything deleted by
2226 <literal>distclean</literal>, plus more: C source files
2227 produced by Bison, tags tables, Info files, and so
2230 <para>One exception, however: <literal>make
2231 maintainer-clean</literal> should not delete
2232 <filename>configure</filename> even if
2233 <filename>configure</filename> can be remade using a rule
2234 in the <filename>Makefile</filename>. More generally,
2235 <literal>make maintainer-clean</literal> should not delete
2236 anything that needs to exist in order to run
2237 <filename>configure</filename> and then begin to build the
2243 <term><literal>check</literal></term>
2245 <para>run the test suite.</para>
2250 <para>All of these standard targets automatically recurse into
2251 sub-directories. Certain other standard targets do not:</para>
2255 <term><literal>configure</literal></term>
2257 <para>is only available in the root directory
2258 <constant>$(FPTOOLS_TOP)</constant>; it has
2259 been discussed in <xref
2260 linkend="sec-build-config"/>.</para>
2265 <term><literal>depend</literal></term>
2267 <para>make a <filename>.depend</filename> file in each
2268 directory that needs it. This <filename>.depend</filename>
2269 file contains mechanically-generated dependency
2270 information; for example, suppose a directory contains a
2271 Haskell source module <filename>Foo.lhs</filename> which
2272 imports another module <literal>Baz</literal>. Then the
2273 generated <filename>.depend</filename> file will contain
2274 the dependency:</para>
2280 <para>which says that the object file
2281 <filename>Foo.o</filename> depends on the interface file
2282 <filename>Baz.hi</filename> generated by compiling module
2283 <literal>Baz</literal>. The <filename>.depend</filename>
2284 file is automatically included by every Makefile.</para>
2289 <term><literal>binary-dist</literal></term>
2291 <para>make a binary distribution. This is the target we
2292 use to build the binary distributions of GHC and
2298 <term><literal>dist</literal></term>
2300 <para>make a source distribution. Note that this target
2301 does “make distclean” as part of its work;
2302 don't use it if you want to keep what you've built.</para>
2307 <para>Most <filename>Makefile</filename>s have targets other
2308 than these. You can discover them by looking in the
2309 <filename>Makefile</filename> itself.</para>
2313 <title>Using a project from the build tree</title>
2315 <para>If you want to build GHC (say) and just use it direct from
2316 the build tree without doing <literal>make install</literal>
2317 first, you can run the in-place driver script:
2318 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2320 <para> Do <emphasis>NOT</emphasis> use
2321 <filename>ghc/compiler/ghc</filename>, or
2322 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2323 scripts intended for installation, and contain hard-wired paths
2324 to the installed libraries, rather than the libraries in the
2327 <para>Happy can similarly be run from the build tree, using
2328 <filename>happy/src/happy-inplace</filename>, and similarly for
2329 Alex and Haddock.</para>
2333 <title>Fast Making</title>
2335 <indexterm><primary>fastmake</primary></indexterm>
2336 <indexterm><primary>dependencies, omitting</primary></indexterm>
2337 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2339 <para>Sometimes the dependencies get in the way: if you've made
2340 a small change to one file, and you're absolutely sure that it
2341 won't affect anything else, but you know that
2342 <command>make</command> is going to rebuild everything anyway,
2343 the following hack may be useful:</para>
2349 <para>This tells the make system to ignore dependencies and just
2350 build what you tell it to. In other words, it's equivalent to
2351 temporarily removing the <filename>.depend</filename> file in
2352 the current directory (where <command>mkdependHS</command> and
2353 friends store their dependency information).</para>
2355 <para>A bit of history: GHC used to come with a
2356 <command>fastmake</command> script that did the above job, but
2357 GNU make provides the features we need to do it without
2358 resorting to a script. Also, we've found that fastmaking is
2359 less useful since the advent of GHC's recompilation checker (see
2360 the User's Guide section on "Separate Compilation").</para>
2364 <sect1 id="sec-makefile-arch">
2365 <title>The <filename>Makefile</filename> architecture</title>
2366 <indexterm><primary>makefile architecture</primary></indexterm>
2368 <para><command>make</command> is great if everything
2369 works—you type <command>gmake install</command> and lo! the
2370 right things get compiled and installed in the right places. Our
2371 goal is to make this happen often, but somehow it often doesn't;
2372 instead some weird error message eventually emerges from the
2373 bowels of a directory you didn't know existed.</para>
2375 <para>The purpose of this section is to give you a road-map to
2376 help you figure out what is going right and what is going
2380 <title>Debugging</title>
2382 <para>Debugging <filename>Makefile</filename>s is something of a
2383 black art, but here's a couple of tricks that we find
2384 particularly useful. The following command allows you to see
2385 the contents of any make variable in the context of the current
2386 <filename>Makefile</filename>:</para>
2388 <screen>$ make show VALUE=HS_SRCS</screen>
2390 <para>where you can replace <literal>HS_SRCS</literal> with the
2391 name of any variable you wish to see the value of.</para>
2393 <para>GNU make has a <option>-d</option> option which generates
2394 a dump of the decision procedure used to arrive at a conclusion
2395 about which files should be recompiled. Sometimes useful for
2396 tracking down problems with superfluous or missing
2397 recompilations.</para>
2401 <title>A small project</title>
2403 <para>To get started, let us look at the
2404 <filename>Makefile</filename> for an imaginary small
2405 <literal>fptools</literal> project, <literal>small</literal>.
2406 Each project in <literal>fptools</literal> has its own directory
2407 in <constant>FPTOOLS_TOP</constant>, so the
2408 <literal>small</literal> project will have its own directory
2409 <constant>FPOOLS_TOP/small/</constant>. Inside the
2410 <filename>small/</filename> directory there will be a
2411 <filename>Makefile</filename>, looking something like
2414 <indexterm><primary>Makefile, minimal</primary></indexterm>
2417 # Makefile for fptools project "small"
2420 include $(TOP)/mk/boilerplate.mk
2422 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2425 include $(TOP)/target.mk
2428 <para>this <filename>Makefile</filename> has three
2433 <para>The first section includes
2436 One of the most important
2437 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2438 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2443 a file of “boilerplate” code from the level
2444 above (which in this case will be
2445 <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2446 As its name suggests, <filename>boilerplate.mk</filename>
2447 consists of a large quantity of standard
2448 <filename>Makefile</filename> code. We discuss this
2449 boilerplate in more detail in <xref linkend="sec-boiler"/>.
2450 <indexterm><primary>include, directive in
2451 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2452 inclusion</primary></indexterm></para>
2454 <para>Before the <literal>include</literal> statement, you
2455 must define the <command>make</command> variable
2456 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2457 to be the directory containing the <filename>mk</filename>
2458 directory in which the <filename>boilerplate.mk</filename>
2459 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2462 include ../mk/boilerplate.mk # NO NO NO
2466 <para>Why? Because the <filename>boilerplate.mk</filename>
2467 file needs to know where it is, so that it can, in turn,
2468 <literal>include</literal> other files. (Unfortunately,
2469 when an <literal>include</literal>d file does an
2470 <literal>include</literal>, the filename is treated relative
2471 to the directory in which <command>gmake</command> is being
2472 run, not the directory in which the
2473 <literal>include</literal>d sits.) In general,
2474 <emphasis>every file <filename>foo.mk</filename> assumes
2476 <filename>$(TOP)/mk/foo.mk</filename>
2477 refers to itself.</emphasis> It is up to the
2478 <filename>Makefile</filename> doing the
2479 <literal>include</literal> to ensure this is the case.</para>
2481 <para>Files intended for inclusion in other
2482 <filename>Makefile</filename>s are written to have the
2483 following property: <emphasis>after
2484 <filename>foo.mk</filename> is <literal>include</literal>d,
2485 it leaves <constant>TOP</constant> containing the same value
2486 as it had just before the <literal>include</literal>
2487 statement</emphasis>. In our example, this invariant
2488 guarantees that the <literal>include</literal> for
2489 <filename>target.mk</filename> will look in the same
2490 directory as that for <filename>boilerplate.mk</filename>.</para>
2494 <para> The second section defines the following standard
2495 <command>make</command> variables:
2496 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2497 (the source files from which is to be built), and
2498 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2499 (the executable binary to be built). We will discuss in
2500 more detail what the “standard variables” are,
2501 and how they affect what happens, in <xref
2502 linkend="sec-targets"/>.</para>
2504 <para>The definition for <constant>SRCS</constant> uses the
2505 useful GNU <command>make</command> construct
2506 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2507 which expands to a list of all the files matching the
2508 pattern <literal>pat</literal> in the current directory. In
2509 this example, <constant>SRCS</constant> is set to the list
2510 of all the <filename>.lhs</filename> and
2511 <filename>.c</filename> files in the directory. (Let's
2512 suppose there is one of each, <filename>Foo.lhs</filename>
2513 and <filename>Baz.c</filename>.)</para>
2517 <para>The last section includes a second file of standard
2519 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2520 It contains the rules that tell <command>gmake</command> how
2521 to make the standard targets (<xref
2522 linkend="sec-standard-targets"/>). Why, you ask, can't this
2523 standard code be part of
2524 <filename>boilerplate.mk</filename>? Good question. We
2525 discuss the reason later, in <xref
2526 linkend="sec-boiler-arch"/>.</para>
2528 <para>You do not <emphasis>have</emphasis> to
2529 <literal>include</literal> the
2530 <filename>target.mk</filename> file. Instead, you can write
2531 rules of your own for all the standard targets. Usually,
2532 though, you will find quite a big payoff from using the
2533 canned rules in <filename>target.mk</filename>; the price
2534 tag is that you have to understand what canned rules get
2535 enabled, and what they do (<xref
2536 linkend="sec-targets"/>).</para>
2540 <para>In our example <filename>Makefile</filename>, most of the
2541 work is done by the two <literal>include</literal>d files. When
2542 you say <command>gmake all</command>, the following things
2547 <para><command>gmake</command> figures out that the object
2548 files are <filename>Foo.o</filename> and
2549 <filename>Baz.o</filename>.</para>
2553 <para>It uses a boilerplate pattern rule to compile
2554 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2555 using a Haskell compiler. (Which one? That is set in the
2556 build configuration.)</para>
2560 <para>It uses another standard pattern rule to compile
2561 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2562 using a C compiler. (Ditto.)</para>
2566 <para>It links the resulting <filename>.o</filename> files
2567 together to make <literal>small</literal>, using the Haskell
2568 compiler to do the link step. (Why not use
2569 <command>ld</command>? Because the Haskell compiler knows
2570 what standard libraries to link in. How did
2571 <command>gmake</command> know to use the Haskell compiler to
2572 do the link, rather than the C compiler? Because we set the
2573 variable <constant>HS_PROG</constant> rather than
2574 <constant>C_PROG</constant>.)</para>
2578 <para>All <filename>Makefile</filename>s should follow the above
2579 three-section format.</para>
2583 <title>A larger project</title>
2585 <para>Larger projects are usually structured into a number of
2586 sub-directories, each of which has its own
2587 <filename>Makefile</filename>. (In very large projects, this
2588 sub-structure might be iterated recursively, though that is
2589 rare.) To give you the idea, here's part of the directory
2590 structure for the (rather large) GHC project:</para>
2600 ...source files for documentation...
2603 ...source files for driver...
2606 parser/...source files for parser...
2607 renamer/...source files for renamer...
2611 <para>The sub-directories <filename>docs</filename>,
2612 <filename>driver</filename>, <filename>compiler</filename>, and
2613 so on, each contains a sub-component of GHC, and each has its
2614 own <filename>Makefile</filename>. There must also be a
2615 <filename>Makefile</filename> in
2616 <filename>$(FPTOOLS_TOP)/ghc</filename>.
2617 It does most of its work by recursively invoking
2618 <command>gmake</command> on the <filename>Makefile</filename>s
2619 in the sub-directories. We say that
2620 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2621 <filename>Makefile</filename></emphasis>, because it does little
2622 except organise its children, while the
2623 <filename>Makefile</filename>s in the sub-directories are all
2624 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2625 principle the sub-directories might themselves contain a
2626 non-leaf <filename>Makefile</filename> and several
2627 sub-sub-directories, but that does not happen in GHC.)</para>
2629 <para>The <filename>Makefile</filename> in
2630 <filename>ghc/compiler</filename> is considered a leaf
2631 <filename>Makefile</filename> even though the
2632 <filename>ghc/compiler</filename> has sub-directories, because
2633 these sub-directories do not themselves have
2634 <filename>Makefile</filename>s in them. They are just used to
2635 structure the collection of modules that make up GHC, but all
2636 are managed by the single <filename>Makefile</filename> in
2637 <filename>ghc/compiler</filename>.</para>
2639 <para>You will notice that <filename>ghc/</filename> also
2640 contains a directory <filename>ghc/mk/</filename>. It contains
2641 GHC-specific <filename>Makefile</filename> boilerplate code.
2642 More precisely:</para>
2646 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2647 at the top of <filename>ghc/Makefile</filename>, and of all
2648 the leaf <filename>Makefile</filename>s in the
2649 sub-directories. It in turn <literal>include</literal>s the
2650 main boilerplate file
2651 <filename>mk/boilerplate.mk</filename>.</para>
2655 <para><filename>ghc/mk/target.mk</filename> is
2656 <literal>include</literal>d at the bottom of
2657 <filename>ghc/Makefile</filename>, and of all the leaf
2658 <filename>Makefile</filename>s in the sub-directories. It
2659 in turn <literal>include</literal>s the file
2660 <filename>mk/target.mk</filename>.</para>
2664 <para>So these two files are the place to look for GHC-wide
2665 customisation of the standard boilerplate.</para>
2668 <sect2 id="sec-boiler-arch">
2669 <title>Boilerplate architecture</title>
2670 <indexterm><primary>boilerplate architecture</primary></indexterm>
2672 <para>Every <filename>Makefile</filename> includes a
2673 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2674 file at the top, and
2675 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2676 file at the bottom. In this section we discuss what is in these
2677 files, and why there have to be two of them. In general:</para>
2681 <para><filename>boilerplate.mk</filename> consists of:</para>
2685 <para><emphasis>Definitions of millions of
2686 <command>make</command> variables</emphasis> that
2687 collectively specify the build configuration. Examples:
2688 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2689 the options to feed to the Haskell compiler;
2690 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2691 the sub-directories to enable within the
2692 <literal>nofib</literal> project;
2693 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2694 the name of the Haskell compiler to use when compiling
2695 GHC in the <literal>ghc</literal> project.</para>
2699 <para><emphasis>Standard pattern rules</emphasis> that
2700 tell <command>gmake</command> how to construct one file
2701 from another.</para>
2705 <para><filename>boilerplate.mk</filename> needs to be
2706 <literal>include</literal>d at the <emphasis>top</emphasis>
2707 of each <filename>Makefile</filename>, so that the user can
2708 replace the boilerplate definitions or pattern rules by
2709 simply giving a new definition or pattern rule in the
2710 <filename>Makefile</filename>. <command>gmake</command>
2711 simply takes the last definition as the definitive one.</para>
2713 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2714 definitions, it is also quite common to
2715 <emphasis>augment</emphasis> them. For example, a
2716 <filename>Makefile</filename> might say:</para>
2722 <para>thereby adding “<option>-O</option>” to
2724 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2728 <para><filename>target.mk</filename> contains
2729 <command>make</command> rules for the standard targets
2730 described in <xref linkend="sec-standard-targets"/>. These
2731 rules are selectively included, depending on the setting of
2732 certain <command>make</command> variables. These variables
2733 are usually set in the middle section of the
2734 <filename>Makefile</filename> between the two
2735 <literal>include</literal>s.</para>
2737 <para><filename>target.mk</filename> must be included at the
2738 end (rather than being part of
2739 <filename>boilerplate.mk</filename>) for several tiresome
2745 <para><command>gmake</command> commits target and
2746 dependency lists earlier than it should. For example,
2747 <filename>target.mk</filename> has a rule that looks
2751 $(HS_PROG) : $(OBJS)
2752 $(HC) $(LD_OPTS) $< -o $@
2755 <para>If this rule was in
2756 <filename>boilerplate.mk</filename> then
2757 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2759 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2760 would not have their final values at the moment
2761 <command>gmake</command> encountered the rule. Alas,
2762 <command>gmake</command> takes a snapshot of their
2763 current values, and wires that snapshot into the rule.
2764 (In contrast, the commands executed when the rule
2765 “fires” are only substituted at the moment
2766 of firing.) So, the rule must follow the definitions
2767 given in the <filename>Makefile</filename> itself.</para>
2771 <para>Unlike pattern rules, ordinary rules cannot be
2772 overriden or replaced by subsequent rules for the same
2773 target (at least, not without an error message).
2774 Including ordinary rules in
2775 <filename>boilerplate.mk</filename> would prevent the
2776 user from writing rules for specific targets in specific
2781 <para>There are a couple of other reasons I've
2782 forgotten, but it doesn't matter too much.</para>
2789 <sect2 id="sec-boiler">
2790 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2791 <indexterm><primary>boilerplate.mk</primary></indexterm>
2793 <para>If you look at
2794 <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
2795 you will find that it consists of the following sections, each
2796 held in a separate file:</para>
2800 <term><filename>config.mk</filename>
2801 <indexterm><primary>config.mk</primary></indexterm>
2804 <para>is the build configuration file we discussed at
2805 length in <xref linkend="sec-build-config"/>.</para>
2810 <term><filename>paths.mk</filename>
2811 <indexterm><primary>paths.mk</primary></indexterm>
2814 <para>defines <command>make</command> variables for
2815 pathnames and file lists. This file contains code for
2816 automatically compiling lists of source files and deriving
2817 lists of object files from those. The results can be
2818 overriden in the <filename>Makefile</filename>, but in
2819 most cases the automatic setup should do the right
2822 <para>The following variables may be set in the
2823 <filename>Makefile</filename> to affect how the automatic
2824 source file search is done:</para>
2828 <term><literal>ALL_DIRS</literal>
2829 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
2832 <para>Set to a list of directories to search in
2833 addition to the current directory for source
2839 <term><literal>EXCLUDE_SRCS</literal>
2840 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
2843 <para>Set to a list of source files (relative to the
2844 current directory) to omit from the automatic
2845 search. The source searching machinery is clever
2846 enough to know that if you exclude a source file
2847 from which other sources are derived, then the
2848 derived sources should also be excluded. For
2849 example, if you set <literal>EXCLUDED_SRCS</literal>
2850 to include <filename>Foo.y</filename>, then
2851 <filename>Foo.hs</filename> will also be
2857 <term><literal>EXTRA_SRCS</literal>
2858 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
2861 <para>Set to a list of extra source files (perhaps
2862 in directories not listed in
2863 <literal>ALL_DIRS</literal>) that should be
2869 <para>The results of the automatic source file search are
2870 placed in the following make variables:</para>
2874 <term><literal>SRCS</literal>
2875 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2878 <para>All source files found, sorted and without
2879 duplicates, including those which might not exist
2880 yet but will be derived from other existing sources.
2881 <literal>SRCS</literal> <emphasis>can</emphasis> be
2882 overriden if necessary, in which case the variables
2883 below will follow suit.</para>
2888 <term><literal>HS_SRCS</literal>
2889 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2892 <para>all Haskell source files in the current
2893 directory, including those derived from other source
2894 files (eg. Happy sources also give rise to Haskell
2900 <term><literal>HS_OBJS</literal>
2901 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2904 <para>Object files derived from
2905 <literal>HS_SRCS</literal>.</para>
2910 <term><literal>HS_IFACES</literal>
2911 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2914 <para>Interface files (<literal>.hi</literal> files)
2915 derived from <literal>HS_SRCS</literal>.</para>
2920 <term><literal>C_SRCS</literal>
2921 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2924 <para>All C source files found.</para>
2929 <term><literal>C_OBJS</literal>
2930 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2933 <para>Object files derived from
2934 <literal>C_SRCS</literal>.</para>
2939 <term><literal>SCRIPT_SRCS</literal>
2940 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2943 <para>All script source files found
2944 (<literal>.lprl</literal> files).</para>
2949 <term><literal>SCRIPT_OBJS</literal>
2950 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2953 <para><quote>object</quote> files derived from
2954 <literal>SCRIPT_SRCS</literal>
2955 (<literal>.prl</literal> files).</para>
2960 <term><literal>HSC_SRCS</literal>
2961 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2964 <para>All <literal>hsc2hs</literal> source files
2965 (<literal>.hsc</literal> files).</para>
2970 <term><literal>HAPPY_SRCS</literal>
2971 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2974 <para>All <literal>happy</literal> source files
2975 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2980 <term><literal>OBJS</literal>
2981 <indexterm><primary>OBJS</primary></indexterm>
2984 <para>the concatenation of
2985 <literal>$(HS_OBJS)</literal>,
2986 <literal>$(C_OBJS)</literal>, and
2987 <literal>$(SCRIPT_OBJS)</literal>.</para>
2992 <para>Any or all of these definitions can easily be
2993 overriden by giving new definitions in your
2994 <filename>Makefile</filename>.</para>
2996 <para>What, exactly, does <filename>paths.mk</filename>
2997 consider a <quote>source file</quote> to be? It's based
2998 on the file's suffix (e.g. <filename>.hs</filename>,
2999 <filename>.lhs</filename>, <filename>.c</filename>,
3000 <filename>.hy</filename>, etc), but this is the kind of
3001 detail that changes, so rather than enumerate the source
3002 suffices here the best thing to do is to look in
3003 <filename>paths.mk</filename>.</para>
3008 <term><filename>opts.mk</filename>
3009 <indexterm><primary>opts.mk</primary></indexterm>
3012 <para>defines <command>make</command> variables for option
3013 strings to pass to each program. For example, it defines
3014 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
3015 the option strings to pass to the Haskell compiler. See
3016 <xref linkend="sec-suffix"/>.</para>
3021 <term><filename>suffix.mk</filename>
3022 <indexterm><primary>suffix.mk</primary></indexterm>
3025 <para>defines standard pattern rules—see <xref
3026 linkend="sec-suffix"/>.</para>
3031 <para>Any of the variables and pattern rules defined by the
3032 boilerplate file can easily be overridden in any particular
3033 <filename>Makefile</filename>, because the boilerplate
3034 <literal>include</literal> comes first. Definitions after this
3035 <literal>include</literal> directive simply override the default
3036 ones in <filename>boilerplate.mk</filename>.</para>
3039 <sect2 id="sec-suffix">
3040 <title>Pattern rules and options</title>
3041 <indexterm><primary>Pattern rules</primary></indexterm>
3044 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
3045 defines standard <emphasis>pattern rules</emphasis> that say how
3046 to build one kind of file from another, for example, how to
3047 build a <filename>.o</filename> file from a
3048 <filename>.c</filename> file. (GNU <command>make</command>'s
3049 <emphasis>pattern rules</emphasis> are more powerful and easier
3050 to use than Unix <command>make</command>'s <emphasis>suffix
3051 rules</emphasis>.)</para>
3053 <para>Almost all the rules look something like this:</para>
3058 $(CC) $(CC_OPTS) -c $< -o $@
3061 <para>Here's how to understand the rule. It says that
3062 <emphasis>something</emphasis><filename>.o</filename> (say
3063 <filename>Foo.o</filename>) can be built from
3064 <emphasis>something</emphasis><filename>.c</filename>
3065 (<filename>Foo.c</filename>), by invoking the C compiler (path
3066 name held in <constant>$(CC)</constant>), passing to it
3067 the options <constant>$(CC_OPTS)</constant> and
3068 the rule's dependent file of the rule
3069 <literal>$<</literal> (<filename>Foo.c</filename> in
3070 this case), and putting the result in the rule's target
3071 <literal>$@</literal> (<filename>Foo.o</filename> in this
3074 <para>Every program is held in a <command>make</command>
3075 variable defined in <filename>mk/config.mk</filename>—look
3076 in <filename>mk/config.mk</filename> for the complete list. One
3077 important one is the Haskell compiler, which is called
3078 <constant>$(HC)</constant>.</para>
3080 <para>Every program's options are are held in a
3081 <command>make</command> variables called
3082 <constant><prog>_OPTS</constant>. the
3083 <constant><prog>_OPTS</constant> variables are
3084 defined in <filename>mk/opts.mk</filename>. Almost all of them
3085 are defined like this:</para>
3089 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
3092 <para>The four variables from which
3093 <constant>CC_OPTS</constant> is built have the following
3098 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3100 <para>options passed to all C compilations.</para>
3105 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3107 <para>options passed to C compilations for way
3108 <literal><way></literal>. For example,
3109 <constant>WAY_mp_CC_OPTS</constant>
3110 gives options to pass to the C compiler when compiling way
3111 <literal>mp</literal>. The variable
3112 <constant>WAY_CC_OPTS</constant> holds
3113 options to pass to the C compiler when compiling the
3114 standard way. (<xref linkend="sec-ways"/> dicusses
3115 multi-way compilation.)</para>
3120 <term><constant><module>_CC_OPTS</constant>:</term>
3122 <para>options to pass to the C compiler that are specific
3123 to module <literal><module></literal>. For example,
3124 <constant>SMap_CC_OPTS</constant> gives the
3125 specific options to pass to the C compiler when compiling
3126 <filename>SMap.c</filename>.</para>
3131 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3133 <para>extra options to pass to all C compilations. This
3134 is intended for command line use, thus:</para>
3137 gmake libHS.a EXTRA_CC_OPTS="-v"
3144 <sect2 id="sec-targets">
3145 <title>The main <filename>mk/target.mk</filename> file</title>
3146 <indexterm><primary>target.mk</primary></indexterm>
3148 <para><filename>target.mk</filename> contains canned rules for
3149 all the standard targets described in <xref
3150 linkend="sec-standard-targets"/>. It is complicated by the fact
3151 that you don't want all of these rules to be active in every
3152 <filename>Makefile</filename>. Rather than have a plethora of
3153 tiny files which you can include selectively, there is a single
3154 file, <filename>target.mk</filename>, which selectively includes
3155 rules based on whether you have defined certain variables in
3156 your <filename>Makefile</filename>. This section explains what
3157 rules you get, what variables control them, and what the rules
3158 do. Hopefully, you will also get enough of an idea of what is
3159 supposed to happen that you can read and understand any weird
3160 special cases yourself.</para>
3164 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3166 <para>If <constant>HS_PROG</constant> is defined,
3167 you get rules with the following targets:</para>
3171 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3173 <para>itself. This rule links
3174 <constant>$(OBJS)</constant> with the Haskell
3175 runtime system to get an executable called
3176 <constant>$(HS_PROG)</constant>.</para>
3181 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3184 <constant>$(HS_PROG)</constant> in
3185 <constant>$(bindir)</constant>.</para>
3194 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3196 <para>is similar to <constant>HS_PROG</constant>,
3197 except that the link step links
3198 <constant>$(C_OBJS)</constant> with the C
3199 runtime system.</para>
3204 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3206 <para>is similar to <constant>HS_PROG</constant>,
3207 except that it links
3208 <constant>$(LIB_OBJS)</constant> to make the
3209 library archive <constant>$(LIBRARY)</constant>,
3210 and <literal>install</literal> installs it in
3211 <constant>$(libdir)</constant>.</para>
3216 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3218 <para>…</para>
3223 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3225 <para>…</para>
3230 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3232 <para>If <constant>HS_SRCS</constant> is defined
3233 and non-empty, a rule for the target
3234 <literal>depend</literal> is included, which generates
3235 dependency information for Haskell programs. Similarly
3236 for <constant>C_SRCS</constant>.</para>
3241 <para>All of these rules are “double-colon” rules,
3245 install :: $(HS_PROG)
3246 ...how to install it...
3249 <para>GNU <command>make</command> treats double-colon rules as
3250 separate entities. If there are several double-colon rules for
3251 the same target it takes each in turn and fires it if its
3252 dependencies say to do so. This means that you can, for
3253 example, define both <constant>HS_PROG</constant> and
3254 <constant>LIBRARY</constant>, which will generate two rules for
3255 <literal>install</literal>. When you type <command>gmake
3256 install</command> both rules will be fired, and both the program
3257 and the library will be installed, just as you wanted.</para>
3260 <sect2 id="sec-subdirs">
3261 <title>Recursion</title>
3262 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3263 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3265 <para>In leaf <filename>Makefile</filename>s the variable
3266 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3267 is undefined. In non-leaf <filename>Makefile</filename>s,
3268 <constant>SUBDIRS</constant> is set to the list of
3269 sub-directories that contain subordinate
3270 <filename>Makefile</filename>s. <emphasis>It is up to you to
3271 set <constant>SUBDIRS</constant> in the
3272 <filename>Makefile</filename>.</emphasis> There is no automation
3273 here—<constant>SUBDIRS</constant> is too important to
3276 <para>When <constant>SUBDIRS</constant> is defined,
3277 <filename>target.mk</filename> includes a rather neat rule for
3278 the standard targets (<xref linkend="sec-standard-targets"/> that
3279 simply invokes <command>make</command> recursively in each of
3280 the sub-directories.</para>
3282 <para><emphasis>These recursive invocations are guaranteed to
3283 occur in the order in which the list of directories is specified
3284 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3285 be important. For example, when you say <command>gmake
3286 boot</command> it can be important that the recursive invocation
3287 of <command>make boot</command> is done in one sub-directory
3288 (the include files, say) before another (the source files).
3289 Generally, put the most independent sub-directory first, and the
3290 most dependent last.</para>
3293 <sect2 id="sec-ways">
3294 <title>Way management</title>
3295 <indexterm><primary>way management</primary></indexterm>
3297 <para>We sometimes want to build essentially the same system in
3298 several different “ways”. For example, we want to build GHC's
3299 <literal>Prelude</literal> libraries with and without profiling,
3300 so that there is an appropriately-built library archive to link
3301 with when the user compiles his program. It would be possible
3302 to have a completely separate build tree for each such “way”,
3303 but it would be horribly bureaucratic, especially since often
3304 only parts of the build tree need to be constructed in multiple
3308 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3309 contains some clever magic to allow you to build several
3310 versions of a system; and to control locally how many versions
3311 are built and how they differ. This section explains the
3314 <para>The files for a particular way are distinguished by
3315 munging the suffix. The <quote>normal way</quote> is always
3316 built, and its files have the standard suffices
3317 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3318 In addition, you can build one or more extra ways, each
3319 distinguished by a <emphasis>way tag</emphasis>. The object
3320 files and interface files for one of these extra ways are
3321 distinguished by their suffix. For example, way
3322 <literal>mp</literal> has files
3323 <filename>.mp_o</filename> and
3324 <filename>.mp_hi</filename>. Library archives have their
3325 way tag the other side of the dot, for boring reasons; thus,
3326 <filename>libHS_mp.a</filename>.</para>
3328 <para>A <command>make</command> variable called
3329 <constant>way</constant> holds the current way tag.
3330 <emphasis><constant>way</constant> is only ever set on the
3331 command line of <command>gmake</command></emphasis> (usually in
3332 a recursive invocation of <command>gmake</command> by the
3333 system). It is never set inside a
3334 <filename>Makefile</filename>. So it is a global constant for
3335 any one invocation of <command>gmake</command>. Two other
3336 <command>make</command> variables,
3337 <constant>way_</constant> and
3338 <constant>_way</constant> are immediately derived from
3339 <constant>$(way)</constant> and never altered. If
3340 <constant>way</constant> is not set, then neither are
3341 <constant>way_</constant> and
3342 <constant>_way</constant>, and the invocation of
3343 <command>make</command> will build the <quote>normal
3344 way</quote>. If <constant>way</constant> is set, then the other
3345 two variables are set in sympathy. For example, if
3346 <constant>$(way)</constant> is “<literal>mp</literal>”,
3347 then <constant>way_</constant> is set to
3348 “<literal>mp_</literal>” and
3349 <constant>_way</constant> is set to
3350 “<literal>_mp</literal>”. These three variables are
3351 then used when constructing file names.</para>
3353 <para>So how does <command>make</command> ever get recursively
3354 invoked with <constant>way</constant> set? There are two ways
3355 in which this happens:</para>
3359 <para>For some (but not all) of the standard targets, when
3360 in a leaf sub-directory, <command>make</command> is
3361 recursively invoked for each way tag in
3362 <constant>$(WAYS)</constant>. You set
3363 <constant>WAYS</constant> in the
3364 <filename>Makefile</filename> to the list of way tags you
3365 want these targets built for. The mechanism here is very
3366 much like the recursive invocation of
3367 <command>make</command> in sub-directories (<xref
3368 linkend="sec-subdirs"/>). It is up to you to set
3369 <constant>WAYS</constant> in your
3370 <filename>Makefile</filename>; this is how you control what
3371 ways will get built.</para>
3375 <para>For a useful collection of targets (such as
3376 <filename>libHS_mp.a</filename>,
3377 <filename>Foo.mp_o</filename>) there is a rule which
3378 recursively invokes <command>make</command> to make the
3379 specified target, setting the <constant>way</constant>
3380 variable. So if you say <command>gmake
3381 Foo.mp_o</command> you should see a recursive
3382 invocation <command>gmake Foo.mp_o way=mp</command>,
3383 and <emphasis>in this recursive invocation the pattern rule
3384 for compiling a Haskell file into a <filename>.o</filename>
3385 file will match</emphasis>. The key pattern rules (in
3386 <filename>suffix.mk</filename>) look like this:
3390 $(HC) $(HC_OPTS) $< -o $@
3397 <para>You can invoke <command>make</command> with a
3398 particular <literal>way</literal> setting yourself, in order
3399 to build files related to a particular
3400 <literal>way</literal> in the current directory. eg.
3406 will build files for the profiling way only in the current
3413 <title>When the canned rule isn't right</title>
3415 <para>Sometimes the canned rule just doesn't do the right thing.
3416 For example, in the <literal>nofib</literal> suite we want the
3417 link step to print out timing information. The thing to do here
3418 is <emphasis>not</emphasis> to define
3419 <constant>HS_PROG</constant> or
3420 <constant>C_PROG</constant>, and instead define a special
3421 purpose rule in your own <filename>Makefile</filename>. By
3422 using different variable names you will avoid the canned rules
3423 being included, and conflicting with yours.</para>
3427 <sect1 id="building-docs">
3428 <title>Building the documentation</title>
3430 <sect2 id="pre-supposed-doc-tools">
3431 <title>Tools for building the Documentation</title>
3433 <para>The following additional tools are required if you want to
3434 format the documentation that comes with the
3435 <literal>fptools</literal> projects:</para>
3440 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3441 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3444 <para>Much of our documentation is written in SGML, using
3445 the DocBook DTD. Instructions on installing and
3446 configuring the DocBook tools are below.</para>
3452 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3453 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3456 <para>A decent TeX distribution is required if you want to
3457 produce printable documentation. We recomment teTeX,
3458 which includes just about everything you need.</para>
3464 <indexterm><primary>Haddock</primary></indexterm>
3467 <para>Haddock is a Haskell documentation tool that we use
3468 for automatically generating documentation from the
3469 library source code. It is an <literal>fptools</literal>
3470 project in itself. To build documentation for the
3471 libraries (<literal>fptools/libraries</literal>) you
3472 should check out and build Haddock in
3473 <literal>fptools/haddock</literal>. Haddock requires GHC
3481 <title>Installing the DocBook tools</title>
3484 <title>Installing the DocBook tools on Linux</title>
3486 <para>If you're on a recent RedHat system (7.0+), you probably
3487 have working DocBook tools already installed. The configure
3488 script should detect your setup and you're away.</para>
3490 <para>If you don't have DocBook tools installed, and you are
3491 using a system that can handle RedHat RPM packages, you can
3492 probably use the <ulink
3493 url="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3494 DocBook tools</ulink>, which is the most shrink-wrapped SGML
3495 suite that we could find. You need all the RPMs except for
3496 psgml (i.e. <filename>docbook</filename>,
3497 <filename>jade</filename>, <filename>jadetex</filename>,
3498 <filename>sgmlcommon</filename> and
3499 <filename>stylesheets</filename>). Note that most of these
3500 RPMs are architecture neutral, so are likely to be found in a
3501 <filename>noarch</filename> directory. The SuSE RPMs also
3502 work; the RedHat ones <emphasis>don't</emphasis> in RedHat 6.2
3503 (7.0 and later should be OK), but they are easy to fix: just
3505 <filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</filename>
3506 to <filename>/usr/lib/sgml/lib/dblib.dsl</filename>. </para>
3510 <title>Installing DocBook on FreeBSD</title>
3512 <para>On FreeBSD systems, the easiest way to get DocBook up
3513 and running is to install it from the ports tree or a
3514 pre-compiled package (packages are available from your local
3515 FreeBSD mirror site).</para>
3517 <para>To use the ports tree, do this:
3519 $ cd /usr/ports/textproc/docproj
3522 This installs the FreeBSD documentation project tools, which
3523 includes everything needed to format the GHC
3524 documentation.</para>
3528 <title>Installing from binaries on Windows</title>
3530 <para>It's a good idea to use Norman Walsh's <ulink
3531 url="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3532 notes</ulink> as a guide. You should get version 3.1 of
3533 DocBook, and note that his file <filename>test.sgm</filename>
3534 won't work, as it needs version 3.0. You should unpack Jade
3535 into <filename>\Jade</filename>, along with the entities,
3536 DocBook into <filename>\docbook</filename>, and the DocBook
3537 stylesheets into <filename>\docbook\stylesheets</filename> (so
3538 they actually end up in
3539 <filename>\docbook\stylesheets\docbook</filename>).</para>
3544 <title>Installing the DocBook tools from source</title>
3549 <para>Install <ulink
3550 url="http://openjade.sourceforge.net/">OpenJade</ulink>
3551 (Windows binaries are available as well as sources). If you
3552 want DVI, PS, or PDF then install JadeTeX from the
3553 <filename>dsssl</filename> subdirectory. (If you get the
3557 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
3560 your version of <command>hyperref</command> is out of date;
3561 download it from CTAN
3562 (<filename>macros/latex/contrib/supported/hyperref</filename>),
3563 and make it, ensuring that you have first removed or renamed
3564 your old copy. If you start getting file not found errors
3565 when making the test for <command>hyperref</command>, you
3566 can abort at that point and proceed straight to
3567 <command>make install</command>, or enter them as
3568 <filename>../</filename><emphasis>filename</emphasis>.)</para>
3570 <para>Make links from <filename>virtex</filename> to
3571 <filename>jadetex</filename> and
3572 <filename>pdfvirtex</filename> to
3573 <filename>pdfjadetex</filename> (otherwise DVI, PostScript
3574 and PDF output will not work). Copy
3575 <filename>dsssl/*.{dtd,dsl}</filename> and
3576 <filename>catalog</filename> to
3577 <filename>/usr/[local/]lib/sgml</filename>.</para>
3581 <title>DocBook and the DocBook stylesheets</title>
3583 <para>Get a Zip of <ulink
3584 url="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ulink>
3585 and install the contents in
3586 <filename>/usr/[local/]/lib/sgml</filename>.</para>
3588 <para>Get the <ulink
3589 url="http://nwalsh.com/docbook/dsssl/">DocBook
3590 stylesheets</ulink> and install in
3591 <filename>/usr/[local/]lib/sgml/stylesheets</filename>
3592 (thereby creating a subdirectory docbook). For indexing,
3593 copy or link <filename>collateindex.pl</filename> from the
3594 DocBook stylesheets archive in <filename>bin</filename> into
3595 a directory on your <constant>PATH</constant>.</para>
3597 <para>Download the <ulink
3598 url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3599 entities</ulink> into
3600 <filename>/usr/[local/]lib/sgml</filename>.</para>
3606 <title>Configuring the DocBook tools</title>
3608 <para>Once the DocBook tools are installed, the configure script
3609 will detect them and set up the build system accordingly. If you
3610 have a system that isn't supported, let us know, and we'll try
3615 <title>Remaining problems</title>
3617 <para>If you install from source, you'll get a pile of warnings
3620 <screen>DTDDECL catalog entries are not supported</screen>
3622 every time you build anything. These can safely be ignored, but
3623 if you find them tedious you can get rid of them by removing all
3624 the <constant>DTDDECL</constant> entries from
3625 <filename>docbook.cat</filename>.</para>
3629 <title>Building the documentation</title>
3631 <para>To build documentation in a certain format, you can
3632 say, for example,</para>
3638 <para>to build HTML documentation below the current directory.
3639 The available formats are: <literal>dvi</literal>,
3640 <literal>ps</literal>, <literal>pdf</literal>,
3641 <literal>html</literal>, and <literal>rtf</literal>. Note that
3642 not all documentation can be built in all of these formats: HTML
3643 documentation is generally supported everywhere, and DocBook
3644 documentation might support the other formats (depending on what
3645 other tools you have installed).</para>
3647 <para>All of these targets are recursive; that is, saying
3648 <literal>make html</literal> will make HTML docs for all the
3649 documents recursively below the current directory.</para>
3651 <para>Because there are many different formats that the DocBook
3652 documentation can be generated in, you have to select which ones
3653 you want by setting the <literal>SGMLDocWays</literal> variable
3654 to a list of them. For example, in
3655 <filename>build.mk</filename> you might have a line:</para>
3658 SGMLDocWays = html ps
3661 <para>This will cause the documentation to be built in the requested
3662 formats as part of the main build (the default is not to build
3663 any documentation at all).</para>
3667 <title>Installing the documentation</title>
3669 <para>To install the documentation, use:</para>
3675 <para>This will install the documentation into
3676 <literal>$(datadir)</literal> (which defaults to
3677 <literal>$(prefix)/share</literal>). The exception is HTML
3678 documentation, which goes into
3679 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3681 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3682 to a list of formats, the <literal>install-docs</literal> target
3683 won't do anything for SGML documentation.</para>
3689 <sect1 id="sec-porting-ghc">
3690 <title>Porting GHC</title>
3692 <para>This section describes how to port GHC to a currenly
3693 unsupported platform. There are two distinct
3694 possibilities:</para>
3698 <para>The hardware architecture for your system is already
3699 supported by GHC, but you're running an OS that isn't
3700 supported (or perhaps has been supported in the past, but
3701 currently isn't). This is the easiest type of porting job,
3702 but it still requires some careful bootstrapping. Proceed to
3703 <xref linkend="sec-booting-from-hc"/>.</para>
3707 <para>Your system's hardware architecture isn't supported by
3708 GHC. This will be a more difficult port (though by comparison
3709 perhaps not as difficult as porting gcc). Proceed to <xref
3710 linkend="unregisterised-porting"/>.</para>
3714 <sect2 id="sec-booting-from-hc">
3715 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3717 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3718 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3719 <indexterm><primary>porting GHC</primary></indexterm>
3721 <para>Bootstrapping GHC on a system without GHC already
3722 installed is achieved by taking the intermediate C files (known
3723 as HC files) from a GHC compilation on a supported system to the
3724 target machine, and compiling them using gcc to get a working
3727 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3728 from C. We recommend using GHC 6.0.1 or
3729 later.</emphasis></para>
3731 <para>HC files are platform-dependent, so you have to get a set
3732 that were generated on similar hardware. There may be some
3733 supplied on the GHC download page, otherwise you'll have to
3734 compile some up yourself, or start from
3735 <emphasis>unregisterised</emphasis> HC files - see <xref
3736 linkend="unregisterised-porting"/>.</para>
3738 <para>The following steps should result in a working GHC build
3739 with full libraries:</para>
3743 <para>Unpack the HC files on top of a fresh source tree
3744 (make sure the source tree version matches the version of
3745 the HC files <emphasis>exactly</emphasis>!). This will
3746 place matching <filename>.hc</filename> files next to the
3747 corresponding Haskell source (<filename>.hs</filename> or
3748 <filename>.lhs</filename>) in the compiler subdirectory
3749 <filename>ghc/compiler</filename> and in the libraries
3750 (subdirectories of <filename>hslibs</filename> and
3751 <literal>libraries</literal>).</para>
3755 <para>The actual build process is fully automated by the
3756 <filename>hc-build</filename> script located in the
3757 <filename>distrib</filename> directory. If you eventually
3758 want to install GHC into the directory
3759 <replaceable>dir</replaceable>, the following
3760 command will execute the whole build process (it won't
3761 install yet):</para>
3764 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3766 <indexterm><primary>--hc-build</primary></indexterm>
3768 <para>By default, the installation directory is
3769 <filename>/usr/local</filename>. If that is what you want,
3770 you may omit the argument to <filename>hc-build</filename>.
3771 Generally, any option given to <filename>hc-build</filename>
3772 is passed through to the configuration script
3773 <filename>configure</filename>. If
3774 <filename>hc-build</filename> successfully completes the
3775 build process, you can install the resulting system, as
3785 <sect2 id="unregisterised-porting">
3786 <title>Porting GHC to a new architecture</title>
3788 <para>The first step in porting to a new architecture is to get
3789 an <firstterm>unregisterised</firstterm> build working. An
3790 unregisterised build is one that compiles via vanilla C only.
3791 By contrast, a registerised build uses the following
3792 architecture-specific hacks for speed:</para>
3796 <para>Global register variables: certain abstract machine
3797 <quote>registers</quote> are mapped to real machine
3798 registers, depending on how many machine registers are
3800 <filename>ghc/includes/MachRegs.h</filename>).</para>
3804 <para>Assembly-mangling: when compiling via C, we feed the
3805 assembly generated by gcc though a Perl script known as the
3806 <firstterm>mangler</firstterm> (see
3807 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3808 mangler rearranges the assembly to support tail-calls and
3809 various other optimisations.</para>
3813 <para>In an unregisterised build, neither of these hacks are
3814 used — the idea is that the C code generated by the
3815 compiler should compile using gcc only. The lack of these
3816 optimisations costs about a factor of two in performance, but
3817 since unregisterised compilation is usually just a step on the
3818 way to a full registerised port, we don't mind too much.</para>
3820 <para>Notes on GHC portability in general: we've tried to stick
3821 to writing portable code in most parts of the system, so it
3822 should compile on any POSIXish system with gcc, but in our
3823 experience most systems differ from the standards in one way or
3824 another. Deal with any problems as they arise - if you get
3825 stuck, ask the experts on
3826 <email>glasgow-haskell-users@haskell.org</email>.</para>
3828 <para>Lots of useful information about the innards of GHC is
3829 available in the <ulink
3830 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3831 Commentary</ulink>, which might be helpful if you run into some
3832 code which needs tweaking for your system.</para>
3835 <title>Cross-compiling to produce an unregisterised GHC</title>
3837 <para>In this section, we explain how to bootstrap GHC on a
3838 new platform, using unregisterised intermediate C files. We
3839 haven't put a great deal of effort into automating this
3840 process, for two reasons: it is done very rarely, and the
3841 process usually requires human intervention to cope with minor
3842 porting issues anyway.</para>
3844 <para>The following step-by-step instructions should result in
3845 a fully working, albeit unregisterised, GHC. Firstly, you
3846 need a machine that already has a working GHC (we'll call this
3847 the <firstterm>host</firstterm> machine), in order to
3848 cross-compile the intermediate C files that we will use to
3849 bootstrap the compiler on the <firstterm>target</firstterm>
3854 <para>On the target machine:</para>
3858 <para>Unpack a source tree (preferably a released
3859 version). We will call the path to the root of this
3860 tree <replaceable>T</replaceable>.</para>
3865 $ cd <replaceable>T</replaceable>
3866 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
3869 <para>You might need to update
3870 <filename>configure.in</filename> to recognise the new
3871 architecture, and re-generate
3872 <filename>configure</filename> with
3873 <literal>autoreconf</literal>.</para>
3878 $ cd <replaceable>T</replaceable>/ghc/includes
3886 <para>On the host machine:</para>
3890 <para>Unpack a source tree (same released version). Call
3891 this directory <replaceable>H</replaceable>.</para>
3896 $ cd <replaceable>H</replaceable>
3903 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3904 with the following contents:</para>
3907 GhcUnregisterised = YES
3908 GhcLibHcOpts = -O -H32m -keep-hc-files
3911 GhcWithNativeCodeGen = NO
3912 GhcWithInterpreter = NO
3913 GhcStage1HcOpts = -O -H32m -fasm
3914 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3920 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3923 <para>change <literal>TARGETPLATFORM</literal>
3924 appropriately, and set the variables involving
3925 <literal>TARGET</literal> to the correct values for
3926 the target platform. This step is necessary because
3927 currently <literal>configure</literal> doesn't cope
3928 with specifying different values for the
3929 <literal>--host</literal> and
3930 <literal>--target</literal> flags.</para>
3933 <para>copy <literal>LeadingUnderscore</literal>
3934 setting from target.</para>
3941 <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
3943 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3944 Note that we are building on the host machine, using the
3945 target machine's <literal>config.h</literal> file. This
3946 is so that the intermediate C files generated here will
3947 be suitable for compiling on the target system.</para>
3952 <para>Touch <literal>config.h</literal>, just to make
3953 sure it doesn't get replaced during the build:</para>
3955 $ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
3959 <para>Now build the compiler:</para>
3961 $ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3962 $ cd <replaceable>H</replaceable>/ghc && make boot && make
3964 <para>Don't worry if the build falls over in the RTS, we
3965 don't need the RTS yet.</para>
3970 $ cd <replaceable>H</replaceable>/libraries
3971 $ make boot && make
3977 $ cd <replaceable>H</replaceable>/ghc
3978 $ make boot stage=2 && make stage=2
3984 $ cd <replaceable>H</replaceable>/ghc/utils
3986 $ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
3987 EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3993 $ cd <replaceable>H</replaceable>
3994 $ make hc-file-bundle Project=Ghc
4000 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
4001 to <filename><replaceable>T</replaceable>/..</filename>.</para>
4007 <para>On the target machine:</para>
4009 <para>At this stage we simply need to bootstrap a compiler
4010 from the intermediate C files we generated above. The
4011 process of bootstrapping from C files is automated by the
4012 script in <literal>distrib/hc-build</literal>, and is
4013 described in <xref linkend="sec-booting-from-hc"/>.</para>
4016 $ ./distrib/hc-build --enable-hc-boot-unregisterised
4019 <para>However, since this is a bootstrap on a new machine,
4020 the automated process might not run to completion the
4021 first time. For that reason, you might want to treat the
4022 <literal>hc-build</literal> script as a list of
4023 instructions to follow, rather than as a fully automated
4024 script. This way you'll be able to restart the process
4025 part-way through if you need to fix anything on the
4028 <para>Don't bother with running
4029 <literal>make install</literal> in the newly
4030 bootstrapped tree; just use the compiler in that tree to
4031 build a fresh compiler from scratch, this time without
4032 booting from C files. Before doing this, you might want
4033 to check that the bootstrapped compiler is generating
4034 working binaries:</para>
4038 main = putStrLn "Hello World!\n"
4040 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
4045 <para>Once you have the unregisterised compiler up and
4046 running, you can use it to start a registerised port. The
4047 following sections describe the various parts of the
4048 system that will need architecture-specific tweaks in
4049 order to get a registerised build going.</para>
4056 <title>Porting the RTS</title>
4058 <para>The following files need architecture-specific code for a
4059 registerised build:</para>
4063 <term><filename>ghc/includes/MachRegs.h</filename>
4064 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
4067 <para>Defines the STG-register to machine-register
4068 mapping. You need to know your platform's C calling
4069 convention, and which registers are generally available
4070 for mapping to global register variables. There are
4071 plenty of useful comments in this file.</para>
4075 <term><filename>ghc/includes/TailCalls.h</filename>
4076 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
4079 <para>Macros that cooperate with the mangler (see <xref
4080 linkend="sec-mangler"/>) to make proper tail-calls
4085 <term><filename>ghc/rts/Adjustor.c</filename>
4086 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
4090 <literal>foreign import "wrapper"</literal>
4092 <literal>foreign export dynamic</literal>).
4093 Not essential for getting GHC bootstrapped, so this file
4094 can be deferred until later if necessary.</para>
4098 <term><filename>ghc/rts/StgCRun.c</filename>
4099 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
4102 <para>The little assembly layer between the C world and
4103 the Haskell world. See the comments and code for the
4104 other architectures in this file for pointers.</para>
4108 <term><filename>ghc/rts/MBlock.h</filename>
4109 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
4111 <term><filename>ghc/rts/MBlock.c</filename>
4112 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
4115 <para>These files are really OS-specific rather than
4116 architecture-specific. In <filename>MBlock.h</filename>
4117 is specified the absolute location at which the RTS
4118 should try to allocate memory on your platform (try to
4119 find an area which doesn't conflict with code or dynamic
4120 libraries). In <filename>Mblock.c</filename> you might
4121 need to tweak the call to <literal>mmap()</literal> for
4128 <sect3 id="sec-mangler">
4129 <title>The mangler</title>
4131 <para>The mangler is an evil Perl-script that rearranges the
4132 assembly code output from gcc to do two main things:</para>
4136 <para>Remove function prologues and epilogues, and all
4137 movement of the C stack pointer. This is to support
4138 tail-calls: every code block in Haskell code ends in an
4139 explicit jump, so we don't want the C-stack overflowing
4140 while we're jumping around between code blocks.</para>
4143 <para>Move the <firstterm>info table</firstterm> for a
4144 closure next to the entry code for that closure. In
4145 unregisterised code, info tables contain a pointer to the
4146 entry code, but in registerised compilation we arrange
4147 that the info table is shoved right up against the entry
4148 code, and addressed backwards from the entry code pointer
4149 (this saves a word in the info table and an extra
4150 indirection when jumping to the closure entry
4155 <para>The mangler is abstracted to a certain extent over some
4156 architecture-specific things such as the particular assembler
4157 directives used to herald symbols. Take a look at the
4158 definitions for other architectures and use these as a
4159 starting point.</para>
4163 <title>The native code generator</title>
4165 <para>The native code generator isn't essential to getting a
4166 registerised build going, but it's a desirable thing to have
4167 because it can cut compilation times in half. The native code
4168 generator is described in some detail in the <ulink
4169 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
4170 commentary</ulink>.</para>
4176 <para>To support GHCi, you need to port the dynamic linker
4177 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
4178 currently supports the ELF and PEi386 object file formats - if
4179 your platform uses one of these then things will be
4180 significantly easier. The majority of Unix platforms use the
4181 ELF format these days. Even so, there are some
4182 machine-specific parts of the ELF linker: for example, the
4183 code for resolving particular relocation types is
4184 machine-specific, so some porting of this code to your
4185 architecture will probaly be necessary.</para>
4187 <para>If your system uses a different object file format, then
4188 you have to write a linker — good luck!</para>
4194 <sect1 id="sec-build-pitfalls">
4195 <title>Known pitfalls in building Glasgow Haskell
4197 <indexterm><primary>problems, building</primary></indexterm>
4198 <indexterm><primary>pitfalls, in building</primary></indexterm>
4199 <indexterm><primary>building pitfalls</primary></indexterm></title>
4202 WARNINGS about pitfalls and known “problems”:
4211 One difficulty that comes up from time to time is running out of space
4212 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
4213 compensate for the vagaries of different sysadmin approaches to temp
4215 <indexterm><primary>tmp, running out of space in</primary></indexterm>
4217 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
4218 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
4221 The best way around it is to say
4224 export TMPDIR=<dir>
4227 in your <filename>build.mk</filename> file.
4228 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
4237 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
4238 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
4246 When compiling via C, you'll sometimes get “warning: assignment from
4247 incompatible pointer type” out of GCC. Harmless.
4254 Similarly, <command>ar</command>chiving warning messages like the following are not
4258 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
4259 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
4269 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
4270 get an “Out of heap space” error message. These can vary with the
4271 vagaries of different systems, it seems. The solution is simple:
4278 If you're compiling with GHC 4.00 or later, then the
4279 <emphasis>maximum</emphasis> heap size must have been reached. This
4280 is somewhat unlikely, since the maximum is set to 64M by default.
4281 Anyway, you can raise it with the
4282 <option>-optCrts-M<size></option> flag (add this flag to
4283 <constant><module>_HC_OPTS</constant>
4284 <command>make</command> variable in the appropriate
4285 <filename>Makefile</filename>).
4292 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4301 and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
4302 <constant><module>_HC_OPTS</constant>.)
4304 Alternatively, just cut to the chase:
4308 % make EXTRA_HC_OPTS=-optCrts-M128M
4317 If you try to compile some Haskell, and you get errors from GCC about
4318 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4319 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4321 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4322 this bug also suggests that you have an old GCC.
4330 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4334 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4335 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4337 ? # or, on some machines: ar s $i
4342 We'd be interested to know if this is still necessary.
4350 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4351 a bit from one Unix to another. One particular gotcha is macro calls
4356 SLIT("Hello, world")
4360 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4361 arguments, so you get
4365 :731: macro `SLIT' used with too many (2) args
4369 Alas, <command>cpp</command> doesn't tell you the offending file!
4371 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4382 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
4384 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
4385 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
4388 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
4390 <para> The build system is built around Unix-y makefiles. Because it's not native,
4391 the Windows situation for building GHC is particularly confusing. This section
4392 tries to clarify, and to establish terminology.</para>
4394 <sect3 id="ghc-mingw"><title>MinGW</title>
4396 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4397 is a collection of header
4398 files and import libraries that allow one to use <command>gcc</command> and produce
4399 native Win32 programs that do not rely on any third-party DLLs. The
4400 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4401 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4405 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
4410 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
4412 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
4413 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
4414 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
4415 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
4416 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
4420 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
4421 compile code that has access to all of Posix. The price is that the executables must be
4422 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
4423 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4424 does not change, but the implementation certainly does. Even the interfaces to functions
4425 it exports seem to change occasionally. </para>
4429 MSYS is a fork of the Cygwin tree, so they
4430 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
4431 through fewer layers, so MSYS is quite a bit faster too.
4434 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
4435 compile binaries that run with no DLL support, on any Win32 system.
4436 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
4437 <command>cvs</command>, <command>ssh</command> etc. To get these, you have to download the
4438 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
4440 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
4441 <command>ssh</command> and so on),
4442 not by programs compiled under MSYS.
4450 <sect3><title>Targeting MinGW</title>
4452 <para>We want GHC to compile programs that work on any Win32 system. Hence:
4455 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
4456 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
4457 will work on any system, but it also means that the programs GHC compiles do not have access
4458 to all of Posix. In particular, they cannot import the (Haskell) Posix
4459 library; they have to do
4460 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
4461 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4465 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
4466 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4469 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
4470 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
4471 that targets Cygwin instead. The up-side of GHC-cygwin is
4472 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4473 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
4476 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
4477 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
4478 GHC; both work fine, though MSYS is rather lighter weight.</para>
4480 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
4481 uses the <command>gcc</command> that you specify using the
4482 <option>--with-gcc</option> flag when you run
4483 <command>configure</command> (see below).
4484 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
4485 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
4486 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
4487 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
4488 used to glom together .o files into a bigger .o file, or a .a file,
4489 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4490 Cygwin and MinGW use the same .o file format. So its ok.
4494 <sect3><title> File names </title>
4496 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
4500 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
4501 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
4503 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
4504 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
4505 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
4510 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
4514 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
4516 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
4522 <sect3><title>Host System vs Target System</title>
4525 In the source code you'll find various ifdefs looking like:
4527 #ifdef mingw32_HOST_OS
4533 #ifdef mingw32_TARGET_OS
4537 These macros are set by the configure script (via the file config.h).
4538 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4541 <para>The "host" system is the one on which GHC itself will be run.</para>
4544 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
4547 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4548 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4555 <sect2><title>Wrapper scripts</title>
4558 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
4559 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
4560 GHC itself as an example:
4563 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
4564 paths to the front of the source file <filename>ghc.sh</filename>,
4565 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
4566 where to find its supporting files.
4570 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
4571 native Windows shell <command>cmd</command> (e.g. limits on the length
4572 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
4573 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
4574 and from that figures out where the supporting files are.
4577 (You can find the layout of GHC's supporting files in the
4578 section "Layout of installed files" of Section 2 of the GHC user guide.)
4581 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
4582 execute a program that has just been built in a build tree. The difference is that the
4583 layout of the supporting files is different.
4584 In this case, whether on Windows or Unix, we always use a shell script. This works OK
4585 on Windows because the script is executed by MSYS or Cygwin, which don't have the
4586 shortcomings of the native Windows <command>cmd</command> shell.
4593 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
4596 This section gives detailed instructions for how to build
4597 GHC from source on your Windows machine. Similar instructions for
4598 installing and running GHC may be found in the user guide. In general,
4599 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4602 Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
4603 before reading section.
4604 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
4605 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
4608 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
4611 MSYS is a lightweight alternative to Cygwin.
4612 You don't need MSYS to <emphasis>use</emphasis> GHC,
4613 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
4614 Here's how to install MSYS.
4617 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
4618 download the following (of course, the version numbers will differ):
4620 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
4622 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
4623 This provides <command>make</command>, <command>autoconf</command>,
4624 <command>ssh</command>, <command>cvs</command> and probably more besides.
4627 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
4631 Set the following environment variables
4633 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path. (Of course, the version number may differ.)
4636 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
4637 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
4640 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
4643 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
4647 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
4654 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
4655 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
4656 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
4657 file has too-liberal permissinos.
4662 <para>Here are some points to bear in mind when using MSYS:
4664 <listitem> <para> MSYS does some kind of special magic to binaries stored in
4665 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
4666 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
4667 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
4668 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
4669 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
4671 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
4675 Win32 has a <command>find</command> command which is not the same as MSYS's find.
4676 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4677 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4678 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4679 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4683 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
4684 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
4685 bzip'd dump.</para></listitem>
4691 <sect2><title>Installing and configuring Cygwin</title>
4693 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4694 The installation process is straightforward; we install it in <filename>c:/cygwin</filename>.
4695 During the installation dialogue, make sure that you select all of the following:
4696 <command>cvs</command>,
4697 <command>openssh</command>,
4698 <command>autoconf</command>,
4699 <command>binutils</command> (includes ld and (I think) ar),
4700 <command>gcc</command>,
4701 <command>flex</command>,
4702 <command>make</command>.
4703 If you miss out any of these, strange things will happen to you. To see thse packages,
4704 click on the "View" button in the "Select Packages"
4705 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
4706 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
4708 <para> Now set the following user environment variables:
4711 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4712 <constant>PATH</constant></para></listitem>
4716 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
4717 don't do this you get very weird messages when you type
4718 <command>make</command>, such as:
4720 /c: /c: No such file or directory
4725 <listitem><para> Set <constant>SHELL</constant> to
4726 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
4727 <constant>SHELL</constant> is what you get.
4730 <listitem><para> Set <constant>HOME</constant> to point to your
4731 home directory. This is where, for example,
4732 <command>bash</command> will look for your <filename>.bashrc</filename>
4733 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4739 There are a few other things to do:
4743 By default, cygwin provides the command shell <filename>ash</filename>
4744 as <filename>sh.exe</filename>. We have often seen build-system problems that
4745 turn out to be due to bugs in <filename>ash</filename>
4747 and length of command lines). On the other hand <filename>bash</filename> seems
4749 So, in <filename>cygwin/bin</filename>
4750 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4751 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4752 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4753 you can't rename a running program!
4759 Some script files used in the make system start with "<command>#!/bin/perl</command>",
4760 (and similarly for <command>sh</command>). Notice the hardwired path!
4761 So you need to ensure that your <filename>/bin</filename> directory has the following
4764 <listitem> <para><command>sh</command></para></listitem>
4765 <listitem> <para><command>perl</command></para></listitem>
4766 <listitem> <para><command>cat</command></para></listitem>
4768 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
4769 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
4770 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
4771 (You can discover where your Cygwin
4772 root directory <filename>/</filename> is by typing <command>mount</command>.)
4773 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
4774 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4775 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4781 <para>Finally, here are some things to be aware of when using Cygwin:
4783 <listitem> <para>Cygwin doesn't deal well with filenames that include
4784 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4788 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4789 magical text in it. So other programs that don't use Cygwin's
4790 I/O libraries won't recognise such files as symlinks.
4791 In particular, programs compiled by GHC are meant to be runnable
4792 without having Cygwin, so they don't use the Cygwin library, so
4793 they don't recognise symlinks.
4797 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
4798 which apply to Cygwin too.
4806 <sect2 id="configure-ssh"><title>Configuring SSH</title>
4808 <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
4809 you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
4810 (not ssh) in the Cygwin list of applications!</para>
4812 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
4816 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
4817 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
4818 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
4819 and run it as follows:
4821 c:\tmp> set CYGWIN32=tty
4822 c:\tmp> c:/user/local/bin/ssh-keygen1
4826 <listitem><para> (Cygwin-only problem, I think.)
4827 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
4828 To determine your home directory <command>ssh</command> first looks in
4829 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
4830 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
4831 the setting of the environment variable $HOME</emphasis>. If the home directory is
4832 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
4834 ssh -v cvs.haskell.org
4836 which makes <command>ssh</command> print out information about its activity.
4838 <para> You can fix this problem, either by correcting the home-directory field in
4839 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
4840 you do that, <command>ssh</command> uses the $HOME environment variable instead.
4846 <para>To protect your
4847 <literal>.ssh</literal> from access by anyone else,
4848 right-click your <literal>.ssh</literal> directory, and
4849 select <literal>Properties</literal>. If you are not on
4850 the access control list, add yourself, and give yourself
4851 full permissions (the second panel). Remove everyone else
4852 from the access control list. Don't leave them there but
4853 deny them access, because 'they' may be a list that
4854 includes you!</para>
4858 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4859 you to have Unix permissions 600 (read/write for owner only)
4860 on the <literal>.ssh/identity</literal> file, else it
4861 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4862 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4863 The solution seems to be to set the $CYGWIN environment
4864 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4865 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4866 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4873 <sect2><title>Other things you need to install</title>
4875 <para>You have to install the following other things to build GHC, listed below.</para>
4877 <para>On Windows you often install executables in directories with spaces, such as
4878 "<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
4879 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
4880 to put binaries for all tools in places with no spaces in their path.
4881 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
4882 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
4883 provided they are in your path.
4887 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4888 This is what you will use to compile GHC. Add it in your
4889 <constant>PATH</constant>: the installer tells you the path element
4890 you need to add upon completion.
4896 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4897 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
4898 build it from the source distribution using
4904 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
4906 Make sure the installation directory is in your
4907 <constant>PATH</constant>.
4912 <para>Install Alex. This can be done by building from the
4913 source distribution in the same way as Happy. Sources are
4914 available from <ulink
4915 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4919 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4920 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
4921 Just pick up a mingw bundle at
4922 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4923 We install it in <filename>c:/mingw</filename>.
4925 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4926 They are only going to get used by explicit access (via the --with-gcc flag you
4927 give to <command>configure</command> later). If you do add them to your path
4928 you are likely to get into a mess because their names overlap with Cygwin binaries.
4934 <para>We use <command>emacs</command> a lot, so we install that too.
4935 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4936 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4937 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4938 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4939 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4940 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4946 <para> Finally, check out a copy of GHC sources from
4947 the CVS repository, following the instructions above (<xref linkend="cvs-access"/>).
4954 <sect2><title>Building GHC</title>
4957 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
4958 the bullets below only tell
4959 you about Windows-specific wrinkles.</para>
4963 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
4964 you'll get an error when you run <filename>./configure</filename>:
4967 creating mk/config.h
4968 mk/config.h is unchanged
4970 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4971 ./configure: ./configure: No such file or directory
4972 configure: error: ./configure failed for ghc
4977 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
4978 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
4981 /usr/bin/autoconf: cannot create configure: permission denied
4983 Solution: delete <filename>configure</filename> first.
4988 After <command>autoreconf</command> run <command>./configure</command> in
4989 <filename>fptools/</filename> thus:
4992 ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
4994 This is the point at which you specify that you are building GHC-mingw
4995 (see <xref linkend="ghc-mingw"/>). </para>
4997 <para> Both these options are important! It's possible to get into
4998 trouble using the wrong C compiler!</para>
5000 Furthermore, it's <emphasis>very important</emphasis> that you specify a
5001 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
5002 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
5003 understand a Cygwin path. For example, if you
5004 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
5005 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
5006 time it tries to invoke it. Worse, the failure comes with
5007 no error message whatsoever. GHC simply fails silently when first invoked,
5008 typically leaving you with this:
5010 make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
5011 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
5012 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
5013 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
5014 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
5015 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
5016 -optc-fomit-frame-pointer -O2 -static
5017 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
5018 make[2]: *** [Adjustor.o] Error 1
5019 make[1]: *** [all] Error 1
5020 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
5021 make: *** [all] Error 1
5027 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
5028 you'll have to do something more like:
5030 ./configure --with-gcc=...the Cygwin gcc...
5036 If you are paranoid, delete <filename>config.cache</filename> if it exists.
5037 This file occasionally remembers out-of-date configuration information, which
5038 can be really confusing.
5042 <listitem><para> You almost certainly want to set
5046 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
5047 This tells the build system not to split each library into a myriad of little object files, one
5048 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
5049 it dramatically increases the time taken to build the libraries in the first place.
5053 <listitem><para> Do not attempt to build the documentation.
5054 It needs all kinds of wierd Jade stuff that we haven't worked out for
5055 Win32.</para></listitem>
projects / ghc-hetmet.git / blob