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.</term>
68 <indexterm><primary>CVS repository</primary>
71 <para>We make releases infrequently. If you want more
72 up-to-the minute (but less tested) source code then you need
73 to get access to our CVS repository.</para>
75 <para>All the <literal>fptools</literal> source code is held
76 in a CVS repository. CVS is a pretty good source-code
77 control system, and best of all it works over the
80 <para>The repository holds source code only. It holds no
81 mechanically generated files at all. So if you check out a
82 source tree from CVS you will need to install every utility
83 so that you can build all the derived files from
86 <para>More information about our CVS repository can be found
87 in <xref linkend="sec-cvs">.</para>
92 <para>If you are going to do any building from sources (either
93 from a source distribution or the CVS repository) then you need to
94 read all of this manual in detail.</para>
98 <title>Using the CVS repository</title>
100 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
101 sources for various software projects. CVS lets several people
102 work on the same software at the same time, allowing changes to be
103 checked in incrementally. </para>
105 <para>This section is a set of guidelines for how to use our CVS
106 repository, and will probably evolve in time. The main thing to
107 remember is that most mistakes can be undone, but if there's
108 anything you're not sure about feel free to bug the local CVS
109 meister (namely Jeff Lewis
110 <email>jlewis@galconn.com</email>). </para>
112 <sect2 id="cvs-access">
113 <title>Getting access to the CVS Repository</title>
115 <para>You can access the repository in one of two ways:
116 read-only (<xref linkend="cvs-read-only">), or read-write (<xref
117 linkend="cvs-read-write">).</para>
119 <sect3 id="cvs-read-only">
120 <title>Remote Read-only CVS Access</title>
122 <para>Read-only access is available to anyone - there's no
123 need to ask us first. With read-only CVS access you can do
124 anything except commit changes to the repository. You can
125 make changes to your local tree, and still use CVS's merge
126 facility to keep your tree up to date, and you can generate
127 patches using 'cvs diff' in order to send to us for
130 <para>To get read-only access to the repository:</para>
134 <para>Make sure that <application>cvs</application> is
135 installed on your machine.</para>
138 <para>Set your <literal>$CVSROOT</literal> environment variable to
139 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
140 <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
141 have any trailing spaces on that line, otherwise CVS will respond with
142 a perplexing message like
144 /cvs : no such repository
145 </programlisting></para>
148 <para>Run the command</para>
152 <para>The password is simply <literal>cvs</literal>. This
153 sets up a file in your home directory called
154 <literal>.cvspass</literal>, which squirrels away the
155 dummy password, so you only need to do this step once.</para>
159 <para>Now go to <xref linkend="cvs-first">.</para>
164 <sect3 id="cvs-read-write">
165 <title>Remote Read-Write CVS Access</title>
167 <para>We generally supply read-write access to folk doing
168 serious development on some part of the source tree, when
169 going through us would be a pain. If you're developing some
170 feature, or think you have the time and inclination to fix
171 bugs in our sources, feel free to ask for read-write
172 access. There is a certain amount of responsibility that goes
173 with commit privileges; we are more likely to grant you access
174 if you've demonstrated your competence by sending us patches
175 via mail in the past.</para>
177 <para>To get remote read-write CVS access, you need to do the
178 following steps.</para>
182 <para>Make sure that <literal>cvs</literal> and
183 <literal>ssh</literal> are both installed on your
188 <para>Generate a DSA private-key/public-key pair, thus:</para>
192 <para>(<literal>ssh-keygen</literal> comes with
193 <literal>ssh</literal>.) Running <literal>ssh-keygen
194 -d</literal> creates the private and public keys in
195 <literal>$HOME/.ssh/id_dsa</literal> and
196 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
197 (assuming you accept the standard defaults).</para>
199 <para><literal>ssh-keygen -d</literal> will only work if
200 you have Version 2 <literal>ssh</literal> installed; it
201 will fail harmlessly otherwise. If you only have Version
202 1 you can instead generate an RSA key pair using plain</para>
207 <para>Doing so creates the private and public RSA keys in
208 <literal>$HOME/.ssh/identity</literal> and
209 <literal>$HOME/.ssh/identity.pub</literal>
212 <para>[Deprecated.] Incidentally, you can force a Version
213 2 <literal>ssh</literal> to use the Version 1 protocol by
214 creating <literal>$HOME/config</literal> with the
215 following in it:</para>
223 <para>In both cases, <literal>ssh-keygen</literal> will
224 ask for a <firstterm>passphrase</firstterm>. The
225 passphrase is a password that protects your private key.
226 In response to the 'Enter passphrase' question, you can
230 <para>[Recommended.] Enter a passphrase, which you
231 will quote each time you use CVS.
232 <literal>ssh-agent</literal> makes this entirely
236 <para>[Deprecated.] Just hit return (i.e. use an empty
237 passphrase); then you won't need to quote the
238 passphrase when using CVS. The downside is that
239 anyone who can see into your <literal>.ssh</literal>
240 directory, and thereby get your private key, can mess
241 up the repository. So you must keep the
242 <literal>.ssh</literal> directory with draconian
243 no-access permissions.</para>
249 <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
256 <para>Send a message to to the CVS repository
257 administrator (currently Jeff Lewis
258 <email>jeff@galconn.com</email>), containing:</para>
261 <para>Your desired user-name.</para>
264 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
265 <literal>.ssh/identity.pub</literal>).</para>
268 <para>He will set up your account.</para>
272 <para>Set the following environment variables:</para>
276 <constant>$HOME</constant>: points to your home directory. This is where CVS
277 will look for its <filename>.cvsrc</filename> file.
283 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
285 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
286 <literal>ssh</literal> assumes that your CVS client
287 understands how to execute shell script
288 ("#!"s,really), which is what
289 <literal>ssh</literal> is. This may not be the case on
290 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
291 <literal>ssh1</literal>.</para>
295 <para><literal>$CVSROOT</literal> to
296 <literal>:ext:</literal><replaceable>your-username</replaceable>
297 <literal>@cvs.haskell.org:/home/cvs/root</literal>
298 where <replaceable>your-username</replaceable> is your user name on
299 <literal>cvs.haskell.org</literal>.
301 <para>The <literal>CVSROOT</literal> environment variable will
302 be recorded in the checked-out tree, so you don't need to set
303 this every time. </para>
309 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
310 if you want to use an Emacs buffer for typing in those long commit messages.
316 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
317 set this to point to <filename>bash.exe</filename>.
328 Put the following in <filename>$HOME/.cvsrc</filename>:
339 These are the default options for the specified CVS commands,
340 and represent better defaults than the usual ones. (Feel
341 free to change them.)
345 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
346 the 8.3 DOS filesystem, but that restriction should have
347 been lifted by now (i.e., you're using VFAT or later filesystems.) If
348 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
356 <para>[Experts.] Once your account is set up, you can get
357 access from other machines without bothering Jeff, thus:</para>
360 <para>Generate a public/private key pair on the new
364 <para>Use ssh to log in to
365 <literal>cvs.haskell.org</literal>, from your old
369 <para>Add the public key for the new machine to the file
370 <literal>$HOME/ssh/authorized_keys</literal> on
371 <literal>cvs.haskell.org</literal>.
372 (<literal>authorized_keys2</literal>, I think, for Version
376 <para>Make sure that the new version of
377 <literal>authorized_keys</literal> still has 600 file
386 <sect2 id="cvs-first">
387 <title>Checking Out a Source Tree</title>
391 <para>Make sure you set your <literal>CVSROOT</literal>
392 environment variable according to either of the remote
393 methods above. The Approved Way to check out a source tree
394 is as follows:</para>
397 $ cvs checkout fpconfig
400 <para>At this point you have a new directory called
401 <literal>fptools</literal> which contains the basic stuff
402 for the fptools suite, including the configuration files and
403 some other junk. </para>
405 <para>[Windows users.] The following messages appear to be harmless:
407 setsockopt IPTOS_LOWDELAY: Invalid argument
408 setsockopt IPTOS_THROUGHPUT: Invalid argument
413 <para>You can call the fptools directory whatever you like,
414 CVS won't mind: </para>
417 $ mv fptools <replaceable>directory</replaceable>
420 <para> NB: after you've read the CVS manual you might be
421 tempted to try</para>
423 $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
426 <para>instead of checking out <literal>fpconfig</literal>
427 and then renaming it. But this doesn't work, and will
428 result in checking out the entire repository instead of just
429 the <literal>fpconfig</literal> bit.</para>
431 $ cd <replaceable>directory</replaceable>
432 $ cvs checkout ghc hslibs libraries
435 <para>The second command here checks out the relevant
436 modules you want to work on. For a GHC build, for instance,
437 you need at least the <literal>ghc</literal>,
438 <literal>hslibs</literal> and <literal>libraries</literal>
439 modules (for a full list of the projects available, see
440 <xref linkend="projects">).</para>
442 <para>Remember that if you do not have
443 <literal>happy</literal> and/or <literal>Alex</literal>
444 installed, you need to check them out as well.</para>
449 <sect2 id="cvs-committing">
450 <title>Committing Changes</title>
452 <para>This is only if you have read-write access to the
453 repository. For anoncvs users, CVS will issue a "read-only
454 repository" error if you try to commit changes.</para>
458 <para>Build the software, if necessary. Unless you're just
459 working on documentation, you'll probably want to build the
460 software in order to test any changes you make.</para>
464 <para>Make changes. Preferably small ones first.</para>
468 <para>Test them. You can see exactly what changes you've
469 made by using the <literal>cvs diff</literal> command:</para>
473 <para>lists all the changes (using the
474 <literal>diff</literal> command) in and below the current
475 directory. In emacs, <literal>C-c C-v =</literal> runs
476 <literal>cvs diff</literal> on the current buffer and shows
477 you the results.</para>
481 <para>If you changed something in the
482 <literal>fptools/libraries</literal> subdirectories, also run
483 <literal>make html</literal> to check if the documentation can
484 be generated successfully, too.</para>
488 <para>Before checking in a change, you need to update your
495 <para>This pulls in any changes that other people have made,
496 and merges them with yours. If there are any conflicts, CVS
497 will tell you, and you'll have to resolve them before you
498 can check your changes in. The documentation describes what
499 to do in the event of a conflict.</para>
501 <para>It's not always necessary to do a full cvs update
502 before checking in a change, since CVS will always tell you
503 if you try to check in a file that someone else has changed.
504 However, you should still update at regular intervals to
505 avoid making changes that don't work in conjuction with
506 changes that someone else made. Keeping an eye on what goes
507 by on the mailing list can help here.</para>
511 <para>When you're happy that your change isn't going to
512 break anything, check it in. For a one-file change:</para>
515 $ cvs commit <replaceable>filename</replaceable>
518 <para>CVS will then pop up an editor for you to enter a
519 "commit message", this is just a short description
520 of what your change does, and will be kept in the history of
523 <para>If you're using emacs, simply load up the file into a
524 buffer and type <literal>C-x C-q</literal>, and emacs will
525 prompt for a commit message and then check in the file for
528 <para>For a multiple-file change, things are a bit
529 trickier. There are several ways to do this, but this is the
530 way I find easiest. First type the commit message into a
531 temporary file. Then either</para>
534 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
537 <para>or, if nothing else has changed in this part of the
541 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
544 <para>where <replaceable>directory</replaceable> is a common
545 parent directory for all your changes, and
546 <replaceable>commit-message</replaceable> is the name of the
547 file containing the commit message.</para>
549 <para>Shortly afterwards, you'll get some mail from the
550 relevant mailing list saying which files changed, and giving
551 the commit message. For a multiple-file change, you should
552 still get only <emphasis>one</emphasis> message.</para>
557 <sect2 id="cvs-update">
558 <title>Updating Your Source Tree</title>
560 <para>It can be tempting to cvs update just part of a source
561 tree to bring in some changes that someone else has made, or
562 before committing your own changes. This is NOT RECOMMENDED!
563 Quite often changes in one part of the tree are dependent on
564 changes in another part of the tree (the
565 <literal>mk/*.mk</literal> files are a good example where
566 problems crop up quite often). Having an inconsistent tree is a
567 major cause of headaches. </para>
569 <para>So, to avoid a lot of hassle, follow this recipe for
570 updating your tree:</para>
574 $ cvs update -P 2>&1 | tee log</screen>
576 <para>Look at the log file, and fix any conflicts (denoted by a
577 <quote>C</quote> in the first column). New directories may have
578 appeared in the repository; CVS doesn't check these out by
579 default, so to get new directories you have to explicitly do
581 $ cvs update -d</screen>
582 in each project subdirectory. Don't do this at the top level,
583 because then <emphasis>all</emphasis> the projects will be
586 <para>If you're using multiple build trees, then for every build
587 tree you have pointing at this source tree, you need to update
588 the links in case any new files have appeared: </para>
591 $ cd <replaceable>build-tree</replaceable>
592 $ lndir <replaceable>source-tree</replaceable>
595 <para>Some files might have been removed, so you need to remove
596 the links pointing to these non-existent files:</para>
599 $ find . -xtype l -exec rm '{}' \;
602 <para>To be <emphasis>really</emphasis> safe, you should do
605 <screen>$ gmake all</screen>
607 <para>from the top-level, to update the dependencies and build
608 any changed files. </para>
611 <sect2 id="cvs-tags">
612 <title>GHC Tag Policy</title>
614 <para>If you want to check out a particular version of GHC,
615 you'll need to know how we tag versions in the repository. The
616 policy (as of 4.04) is:</para>
620 <para>The tree is branched before every major release. The
621 branch tag is <literal>ghc-x-xx-branch</literal>, where
622 <literal>x-xx</literal> is the version number of the release
623 with the <literal>'.'</literal> replaced by a
624 <literal>'-'</literal>. For example, the 4.04 release lives
625 on <literal>ghc-4-04-branch</literal>.</para>
629 <para>The release itself is tagged with
630 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
631 called <literal>ghc-4-06</literal>.</para>
635 <para>We didn't always follow these guidelines, so to see
636 what tags there are for previous versions, do <literal>cvs
637 log</literal> on a file that's been around for a while (like
638 <literal>fptools/ghc/README</literal>).</para>
642 <para>So, to check out a fresh GHC 4.06 tree you would
646 $ cvs co -r ghc-4-06 fpconfig
648 $ cvs co -r ghc-4-06 ghc hslibs
652 <sect2 id="cvs-hints">
653 <title>General Hints</title>
657 <para>As a general rule: commit changes in small units,
658 preferably addressing one issue or implementing a single
659 feature. Provide a descriptive log message so that the
660 repository records exactly which changes were required to
661 implement a given feature/fix a bug. I've found this
662 <emphasis>very</emphasis> useful in the past for finding out
663 when a particular bug was introduced: you can just wind back
664 the CVS tree until the bug disappears.</para>
668 <para>Keep the sources at least *buildable* at any given
669 time. No doubt bugs will creep in, but it's quite easy to
670 ensure that any change made at least leaves the tree in a
671 buildable state. We do nightly builds of GHC to keep an eye
672 on what things work/don't work each day and how we're doing
673 in relation to previous verions. This idea is truely wrecked
674 if the compiler won't build in the first place!</para>
678 <para>To check out extra bits into an already-checked-out
679 tree, use the following procedure. Suppose you have a
680 checked-out fptools tree containing just ghc, and you want
681 to add nofib to it:</para>
692 $ cvs update -d nofib
695 <para>(the -d flag tells update to create a new
696 directory). If you just want part of the nofib suite, you
701 $ cvs checkout nofib/spectral
704 <para>This works because <literal>nofib</literal> is a
705 module in its own right, and spectral is a subdirectory of
706 the nofib module. The path argument to checkout must always
707 start with a module name. There's no equivalent form of this
708 command using <literal>update</literal>.</para>
714 <sect1 id="projects">
715 <title>What projects are there?</title>
717 <para>The <literal>fptools</literal> suite consists of several
718 <firstterm>projects</firstterm>, most of which can be downloaded,
719 built and installed individually. Each project corresponds to a
720 subdirectory in the source tree, and if checking out from CVS then
721 each project can be checked out individually by sitting in the top
722 level of your source tree and typing <command>cvs checkout
723 <replaceable>project</replaceable></command>.</para>
725 <para>Here is a list of the projects currently available:</para>
729 <term><literal>alex</literal></term>
730 <indexterm><primary><literal>alex</literal></primary>
731 <secondary>project</secondary></indexterm>
734 url="http://www.haskell.org/alex/">Alex</ulink> lexical
735 analyser generator for Haskell.</para>
740 <term><literal>ghc</literal></term>
741 <indexterm><primary><literal>ghc</literal></primary>
742 <secondary>project</secondary></indexterm>
744 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
745 Haskell Compiler</ulink> (minus libraries). Absolutely
746 required for building GHC.</para>
751 <term><literal>glafp-utils</literal></term>
752 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
754 <para>Utility programs, some of which are used by the
755 build/installation system. Required for pretty much
761 <term><literal>greencard</literal></term>
762 <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
765 url="http://www.haskell.org/greencard/">GreenCard</ulink>
766 system for generating Haskell foreign function
772 <term><literal>haggis</literal></term>
773 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
776 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
777 Haskell GUI framework.</para>
782 <term><literal>haddock</literal></term>
783 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
786 url="http://www.haskell.org/haddock/">Haddock</ulink>
787 documentation tool.</para>
792 <term><literal>happy</literal></term>
793 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
796 url="http://www.haskell.org/happy/">Happy</ulink> Parser
802 <term><literal>hdirect</literal></term>
803 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
806 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
807 Haskell interoperability tool.</para>
812 <term><literal>hood</literal></term>
813 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
815 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
816 Object Observation Debugger</ulink>.</para>
821 <term><literal>hslibs</literal></term>
822 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
824 <para>Supplemental libraries for GHC
825 (<emphasis>required</emphasis> for building GHC).</para>
830 <term><literal>libraries</literal></term>
831 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
833 <para>Hierarchical Haskell library suite
834 (<emphasis>required</emphasis> for building GHC).</para>
839 <term><literal>mhms</literal></term>
840 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
842 <para>The Modular Haskell Metric System.</para>
847 <term><literal>nofib</literal></term>
848 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
850 <para>The NoFib suite: A collection of Haskell programs used
851 primarily for benchmarking.</para>
856 <term><literal>testsuite</literal></term>
857 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
859 <para>A testing framework, including GHC's regression test
865 <para>So, to build GHC you need at least the
866 <literal>ghc</literal>, <literal>libraries</literal> and
867 <literal>hslibs</literal> projects (a GHC source distribution will
868 already include the bits you need).</para>
871 <sect1 id="sec-build-checks">
872 <title>Things to check before you start</title>
874 <para>Here's a list of things to check before you get
880 <indexterm><primary>Disk space needed</primary></indexterm>
881 <para>Disk space needed: from about 100Mb for a basic GHC
882 build, up to probably 500Mb for a GHC build with everything
883 included (libraries built several different ways,
888 <para>Use an appropriate machine / operating system. <xref
889 linkend="sec-port-info"> lists the supported platforms; if
890 yours isn't amongst these then you can try porting GHC (see
891 <xref linkend="sec-porting-ghc">).</para>
895 <para>Be sure that the “pre-supposed” utilities are
896 installed. <Xref LinkEnd="sec-pre-supposed">
901 <para>If you have any problem when building or installing the
902 Glasgow tools, please check the “known pitfalls” (<Xref
903 LinkEnd="sec-build-pitfalls">). Also check the FAQ for the
904 version you're building, which is part of the User's Guide and
905 available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
908 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
910 <para>If you feel there is still some shortcoming in our
911 procedure or instructions, please report it.</para>
913 <para>For GHC, please see the <ulink
914 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
915 section of the GHC Users' Guide</ulink>, to maximise the
916 usefulness of your report.</para>
918 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
919 <para>If in doubt, please send a message to
920 <email>glasgow-haskell-bugs@haskell.org</email>.
921 <indexterm><primary>bugs</primary><secondary>mailing
922 list</secondary></indexterm></para>
927 <sect1 id="sec-port-info">
928 <title>What machines the Glasgow tools run on</title>
930 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
931 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
932 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
934 <para>The main question is whether or not the Haskell compiler
935 (GHC) runs on your platform.</para>
937 <para>A “platform” is a
938 architecture/manufacturer/operating-system combination, such as
939 <literal>sparc-sun-solaris2</literal>. Other common ones are
940 <literal>alpha-dec-osf2</literal>,
941 <literal>hppa1.1-hp-hpux9</literal>,
942 <literal>i386-unknown-linux</literal>,
943 <literal>i386-unknown-solaris2</literal>,
944 <literal>i386-unknown-freebsd</literal>,
945 <literal>i386-unknown-cygwin32</literal>,
946 <literal>m68k-sun-sunos4</literal>,
947 <literal>mips-sgi-irix5</literal>,
948 <literal>sparc-sun-sunos4</literal>,
949 <literal>sparc-sun-solaris2</literal>,
950 <literal>powerpc-ibm-aix</literal>.</para>
952 <para>Some libraries may only work on a limited number of
953 platforms; for example, a sockets library is of no use unless the
954 operating system supports the underlying BSDisms.</para>
957 <title>What platforms the Haskell compiler (GHC) runs on</title>
959 <indexterm><primary>fully-supported platforms</primary></indexterm>
960 <indexterm><primary>native-code generator</primary></indexterm>
961 <indexterm><primary>registerised ports</primary></indexterm>
962 <indexterm><primary>unregisterised ports</primary></indexterm>
964 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
965 native-code generator; (b) next best is a
966 “registerised” port; (c) the bare minimum is an
967 “unregisterised” port.
968 (“Unregisterised” is so terrible that we won't say
969 more about it).</para>
971 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
972 FreeBSD and Linux, so those are the best supported platforms,
973 unsurprisingly.</para>
975 <para>Here's everything that's known about GHC ports. We
976 identify platforms by their “canonical”
977 CPU/Manufacturer/OS triple.</para>
981 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
982 <indexterm><primary>alpha-dec-osf</primary></indexterm>
983 <indexterm><primary>alpha-dec-linux</primary></indexterm>
984 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
985 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
986 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
989 <para>The OSF port is currently working (as of GHC version
990 5.02.1) and well supported. The native code generator is
991 currently non-working. Other operating systems will
992 require some minor porting.</para>
997 <term>sparc-sun-sunos4</term>
998 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
1000 <para>Probably works with minor tweaks, hasn't been tested
1006 <term>sparc-sun-solaris2</term>
1007 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
1009 <para>Fully supported (at least for Solaris 2.7 and 2.6),
1010 including native-code generator.</para>
1015 <term>sparc-unknown-openbsd</term>
1016 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
1018 <para>Supported, including native-code generator. The
1019 same should also be true of NetBSD</para>
1024 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
1025 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1027 <para>A registerised port is available for version 4.08,
1028 but GHC hasn't been built on that platform since (as far
1029 as we know). No native-code generator.</para>
1034 <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
1035 <indexterm><primary>i386-*-linux</primary></indexterm>
1037 <para>GHC works registerised and has a native code
1038 generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
1039 or later. NOTE about <literal>glibc</literal> versions:
1040 GHC binaries built on a system running <literal>glibc
1041 2.0</literal> won't work on a system running
1042 <literal>glibc 2.1</literal>, and vice versa. In general,
1043 don't expect compatibility between
1044 <literal>glibc</literal> versions, even if the shared
1045 library version hasn't changed.</para>
1050 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
1052 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1054 <para>GHC works registerised. Pre-built packages are
1055 available in the native package format, so if you just
1056 need binaries you're better off just installing the
1057 package (it might even be on your installation
1063 <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
1064 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1066 <para>Supported, with native code generator. Packages are
1067 available through the ports system in the native package
1073 <term>i386-unknown-netbsd (PCs running NetBSD)</term>
1074 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1076 <para>Will require some minor porting effort, but should
1077 work registerised.</para>
1082 <term>i386-unknown-mingw32 (PCs running Windows)</term>
1083 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1085 <para>Fully supported under Win9x, WinNT, Win2k, and
1086 WinXP. Includes a native code generator. Building from
1087 source requires a recent <ulink
1088 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1089 to be installed.</para>
1094 <term>ia64-unknown-linux</term>
1095 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1097 <para>Supported, except there is no native code
1103 <term>x86_64-unknown-linux</term>
1104 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1106 <para>GHC currently works unregisterised. A registerised
1107 port is in progress.</para>
1112 <term>mips-sgi-irix5</term>
1113 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1115 <para>Port has worked in the past, but hasn't been tested
1116 for some time (and will certainly have rotted in various
1117 ways). As usual, we don't have access to machines and
1118 there hasn't been an overwhelming demand for this port,
1119 but feel free to get in touch.</para>
1124 <term>mips64-sgi-irix6</term>
1125 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
1127 <para>GHC currently works unregisterised.</para>
1132 <term>powerpc-ibm-aix</term>
1133 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1135 <para>Port currently doesn't work, needs some minimal
1136 porting effort. As usual, we don't have access to
1137 machines and there hasn't been an overwhelming demand for
1138 this port, but feel free to get in touch.</para>
1143 <term>powerpc-apple-darwin</term>
1144 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1146 <para>Supported registerised. Native code generator is
1147 almost working.</para>
1152 <term>powerpc-apple-linux</term>
1153 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1155 <para>Not supported (yet).</para>
1160 <para>Various other systems have had GHC ported to them in the
1161 distant past, including various Motorola 68k boxes. The 68k
1162 support still remains, but porting to one of these systems will
1163 certainly be a non-trivial task.</para>
1167 <title>What machines the other tools run on</title>
1169 <para>Unless you hear otherwise, the other tools work if GHC
1175 <sect1 id="sec-pre-supposed">
1176 <title>Installing pre-supposed utilities</title>
1178 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1179 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1181 <para>Here are the gory details about some utility programs you
1182 may need; <command>perl</command>, <command>gcc</command> and
1183 <command>happy</command> are the only important
1184 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1185 important if you're going for Parallel Haskell.) The
1186 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1187 script will tell you if you are missing something.</para>
1193 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1194 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1196 <para>GHC is required to build many of the tools, including
1197 GHC itself. If you need to port GHC to your platform
1198 because there isn't a binary distribution of GHC available,
1199 then see <xref linkend="sec-porting-ghc">.</para>
1201 <para>Which version of GHC you need will depend on the
1202 packages you intend to build. GHC itself will normally
1203 build using one of several older versions of itself - check
1204 the announcement or release notes for details.</para>
1210 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1211 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1213 <para><emphasis>You have to have Perl to proceed!</emphasis>
1214 Perl version 5 at least is required. GHC has been known to
1215 tickle bugs in Perl, so if you find that Perl crashes when
1216 running GHC try updating (or downgrading) your Perl
1217 installation. Versions of Perl that we use and are known to
1218 be fairly stable are 5.005 and 5.6.1.</para>
1220 <para>For Win32 platforms, you should use the binary
1221 supplied in the InstallShield (copy it to
1222 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1225 <para>Perl should be put somewhere so that it can be invoked
1226 by the <literal>#!</literal> script-invoking
1227 mechanism. The full pathname may need to be less than 32
1228 characters long on some systems.</para>
1233 <term>GNU C (<command>gcc</command>)</term>
1234 <indexterm><primary>pre-supposed: GCC (GNU C
1235 compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
1236 compiler), pre-supposed</primary></indexterm>
1238 <para>We recommend using GCC version 2.95.2 on all
1239 platforms. Failing that, version 2.7.2 is stable on most
1240 platforms. Earlier versions of GCC can be assumed not to
1241 work, and versions in between 2.7.2 and 2.95.2 (including
1242 <command>egcs</command>) have varying degrees of stability
1243 depending on the platform.</para>
1245 <para>GCC 3.2 is currently known to have problems building
1246 GHC on Sparc, but is stable on x86.</para>
1248 <para>If your GCC dies with “internal error” on
1249 some GHC source file, please let us know, so we can report
1250 it and get things improved. (Exception: on x86
1251 boxes—you may need to fiddle with GHC's
1252 <option>-monly-N-regs</option> option; see the User's
1258 <term>GNU Make</term>
1259 <indexterm><primary>make</primary><secondary>GNU</secondary>
1262 <para>The fptools build system makes heavy use of features
1263 specific to GNU <command>make</command>, so you must have
1264 this installed in order to build any of the fptools
1271 <indexterm><primary>Happy</primary></indexterm>
1273 <para>Happy is a parser generator tool for Haskell, and is
1274 used to generate GHC's parsers. Happy is written in
1275 Haskell, and is a project in the CVS repository
1276 (<literal>fptools/happy</literal>). It can be built from
1277 source, but bear in mind that you'll need GHC installed in
1278 order to build it. To avoid the chicken/egg problem,
1279 install a binary distribution of either Happy or GHC to get
1280 started. Happy distributions are available from <ulink
1281 url="http://www.haskell.org/happy/">Happy's Web
1282 Page</ulink>.</para>
1288 <indexterm><primary>Alex</primary></indexterm>
1290 <para>Alex is a lexical-analyser generator for Haskell,
1291 which GHC uses to generate its lexer. Like Happy, Alex is
1292 written in Haskell and is a project in the CVS repository.
1293 Alex distributions are available from <ulink
1294 url="http://www.haskell.org/alex/">Alex's Web
1295 Page</ulink>.</para>
1300 <term>autoconf</term>
1301 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
1302 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
1304 <para>GNU autoconf is needed if you intend to build from the
1305 CVS sources, it is <emphasis>not</emphasis> needed if you
1306 just intend to build a standard source distribution.</para>
1308 <para>Version 2.52 or later of the autoconf package is required.
1309 NB. version 2.13 will no longer work, as of GHC version
1312 <para><command>autoreconf</command> (from the autoconf package)
1313 recursively builds <command>configure</command> scripts from
1314 the corresponding <filename>configure.ac</filename> and
1315 <filename>aclocal.m4</filename> files. If you modify one of
1316 the latter files, you'll need <command>autoreconf</command> to
1317 rebuild the corresponding <filename>configure</filename>.</para>
1322 <term><command>sed</command></term>
1323 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1324 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1326 <para>You need a working <command>sed</command> if you are
1327 going to build from sources. The build-configuration stuff
1328 needs it. GNU sed version 2.0.4 is no good! It has a bug
1329 in it that is tickled by the build-configuration. 2.0.5 is
1330 OK. Others are probably OK too (assuming we don't create too
1331 elaborate configure scripts.)</para>
1336 <para>One <literal>fptools</literal> project is worth a quick note
1337 at this point, because it is useful for all the others:
1338 <literal>glafp-utils</literal> contains several utilities which
1339 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1340 Like <command>lndir</command> for creating symbolic link
1343 <sect2 id="pre-supposed-gph-tools">
1344 <title>Tools for building parallel GHC (GPH)</title>
1348 <term>PVM version 3:</term>
1349 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1350 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1352 <para>PVM is the Parallel Virtual Machine on which
1353 Parallel Haskell programs run. (You only need this if you
1354 plan to run Parallel Haskell. Concurrent Haskell, which
1355 runs concurrent threads on a uniprocessor doesn't need
1356 it.) Underneath PVM, you can have (for example) a network
1357 of workstations (slow) or a multiprocessor box
1360 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1361 It is readily available on the net; I think I got it from
1362 <literal>research.att.com</literal>, in
1363 <filename>netlib</filename>.</para>
1365 <para>A PVM installation is slightly quirky, but easy to
1366 do. Just follow the <filename>Readme</filename>
1367 instructions.</para>
1372 <term><command>bash</command>:</term>
1373 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1375 <para>Sadly, the <command>gr2ps</command> script, used to
1376 convert “parallelism profiles” to PostScript,
1377 is written in Bash (GNU's Bourne Again shell). This bug
1378 will be fixed (someday).</para>
1384 <sect2 id="pre-supposed-other-tools">
1385 <title>Other useful tools</title>
1390 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1391 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1393 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1394 to build a couple of utilities in
1395 <literal>glafp-utils</literal>. Depending on your
1396 operating system, the supplied <command>lex</command> may
1397 or may not work; you should get the GNU version.</para>
1402 <para>More tools are required if you want to format the documentation
1403 that comes with GHC and other fptools projects. See <xref
1404 linkend="building-docs">.</para>
1408 <sect1 id="sec-building-from-source">
1409 <title>Building from source</title>
1411 <indexterm><primary>Building from source</primary></indexterm>
1412 <indexterm><primary>Source, building from</primary></indexterm>
1414 <para>You've been rash enough to want to build some of the Glasgow
1415 Functional Programming tools (GHC, Happy, nofib, etc.) from
1416 source. You've slurped the source, from the CVS repository or
1417 from a source distribution, and now you're sitting looking at a
1418 huge mound of bits, wondering what to do next.</para>
1420 <para>Gingerly, you type <command>make</command>. Wrong
1423 <para>This rest of this guide is intended for duffers like me, who
1424 aren't really interested in Makefiles and systems configurations,
1425 but who need a mental model of the interlocking pieces so that
1426 they can make them work, extend them consistently when adding new
1427 software, and lay hands on them gently when they don't
1430 <sect2 id="quick-start">
1431 <title>Quick Start</title>
1433 <para>If you are starting from a source distribution, and just
1434 want a completely standard build, then the following should
1437 <screen>$ autoreconf
1443 <para>For GHC, this will do a 2-stage bootstrap build of the
1444 compiler, with profiling libraries, and install the
1447 <para>If you want to do anything at all non-standard, or you
1448 want to do some development, read on...</para>
1451 <sect2 id="sec-source-tree">
1452 <title>Your source tree</title>
1454 <para>The source code is held in your <emphasis>source
1455 tree</emphasis>. The root directory of your source tree
1456 <emphasis>must</emphasis> contain the following directories and
1461 <para><filename>Makefile</filename>: the root
1466 <para><filename>mk/</filename>: the directory that contains
1467 the main Makefile code, shared by all the
1468 <literal>fptools</literal> software.</para>
1472 <para><filename>configure.ac</filename>,
1473 <filename>config.sub</filename>,
1474 <filename>config.guess</filename>: these files support the
1475 configuration process.</para>
1479 <para><filename>install-sh</filename>.</para>
1483 <para>All the other directories are individual
1484 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1485 system—for example, the Glasgow Haskell Compiler
1486 (<literal>ghc</literal>), the Happy parser generator
1487 (<literal>happy</literal>), the <literal>nofib</literal>
1488 benchmark suite, and so on. You can have zero or more of these.
1489 Needless to say, some of them are needed to build others.</para>
1491 <para>The important thing to remember is that even if you want
1492 only one project (<literal>happy</literal>, say), you must have
1493 a source tree whose root directory contains
1494 <filename>Makefile</filename>, <filename>mk/</filename>,
1495 <filename>configure.ac</filename>, and the project(s) you want
1496 (<filename>happy/</filename> in this case). You cannot get by
1497 with just the <filename>happy/</filename> directory.</para>
1501 <title>Build trees</title>
1502 <indexterm><primary>build trees</primary></indexterm>
1503 <indexterm><primary>link trees, for building</primary></indexterm>
1505 <para>If you just want to build the software once on a single
1506 platform, then your source tree can also be your build tree, and
1507 you can skip the rest of this section.</para>
1509 <para>We often want to build multiple versions of our software
1510 for different architectures, or with different options
1511 (e.g. profiling). It's very desirable to share a single copy of
1512 the source code among all these builds.</para>
1514 <para>So for every source tree we have zero or more
1515 <emphasis>build trees</emphasis>. Each build tree is initially
1516 an exact copy of the source tree, except that each file is a
1517 symbolic link to the source file, rather than being a copy of
1518 the source file. There are “standard” Unix
1519 utilities that make such copies, so standard that they go by
1521 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1522 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1523 are two (If you don't have either, the source distribution
1524 includes sources for the X11
1525 <command>lndir</command>—check out
1526 <filename>fptools/glafp-utils/lndir</filename>). See <Xref
1527 LinkEnd="sec-storysofar"> for a typical invocation.</para>
1529 <para>The build tree does not need to be anywhere near the
1530 source tree in the file system. Indeed, one advantage of
1531 separating the build tree from the source is that the build tree
1532 can be placed in a non-backed-up partition, saving your systems
1533 support people from backing up untold megabytes of
1534 easily-regenerated, and rapidly-changing, gubbins. The golden
1535 rule is that (with a single exception—<XRef
1536 LinkEnd="sec-build-config">) <emphasis>absolutely everything in
1537 the build tree is either a symbolic link to the source tree, or
1538 else is mechanically generated</emphasis>. It should be
1539 perfectly OK for your build tree to vanish overnight; an hour or
1540 two compiling and you're on the road again.</para>
1542 <para>You need to be a bit careful, though, that any new files
1543 you create (if you do any development work) are in the source
1544 tree, not a build tree!</para>
1546 <para>Remember, that the source files in the build tree are
1547 <emphasis>symbolic links</emphasis> to the files in the source
1548 tree. (The build tree soon accumulates lots of built files like
1549 <filename>Foo.o</filename>, as well.) You can
1550 <emphasis>delete</emphasis> a source file from the build tree
1551 without affecting the source tree (though it's an odd thing to
1552 do). On the other hand, if you <emphasis>edit</emphasis> a
1553 source file from the build tree, you'll edit the source-tree
1554 file directly. (You can set up Emacs so that if you edit a
1555 source file from the build tree, Emacs will silently create an
1556 edited copy of the source file in the build tree, leaving the
1557 source file unchanged; but the danger is that you think you've
1558 edited the source file whereas actually all you've done is edit
1559 the build-tree copy. More commonly you do want to edit the
1560 source file.)</para>
1562 <para>Like the source tree, the top level of your build tree
1563 must be (a linked copy of) the root directory of the
1564 <literal>fptools</literal> suite. Inside Makefiles, the root of
1565 your build tree is called
1566 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1567 In the rest of this document path names are relative to
1568 <constant>$(FPTOOLS_TOP)</constant> unless
1569 otherwise stated. For example, the file
1570 <filename>ghc/mk/target.mk</filename> is actually
1571 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
1574 <sect2 id="sec-build-config">
1575 <title>Getting the build you want</title>
1577 <para>When you build <literal>fptools</literal> you will be
1578 compiling code on a particular <emphasis>host
1579 platform</emphasis>, to run on a particular <emphasis>target
1580 platform</emphasis> (usually the same as the host
1581 platform)<indexterm><primary>platform</primary></indexterm>.
1582 The difficulty is that there are minor differences between
1583 different platforms; minor, but enough that the code needs to be
1584 a bit different for each. There are some big differences too:
1585 for a different architecture we need to build GHC with a
1586 different native-code generator.</para>
1588 <para>There are also knobs you can turn to control how the
1589 <literal>fptools</literal> software is built. For example, you
1590 might want to build GHC optimised (so that it runs fast) or
1591 unoptimised (so that you can compile it fast after you've
1592 modified it. Or, you might want to compile it with debugging on
1593 (so that extra consistency-checking code gets included) or off.
1596 <para>All of this stuff is called the
1597 <emphasis>configuration</emphasis> of your build. You set the
1598 configuration using a three-step process.</para>
1602 <term>Step 1: get ready for configuration.</term>
1604 <para>NOTE: if you're starting from a source distribution,
1605 rather than CVS sources, you can skip this step.</para>
1607 <para>Change directory to
1608 <constant>$(FPTOOLS_TOP)</constant> and
1609 issue the command</para>
1613 <indexterm><primary>autoreconf</primary></indexterm>
1614 <para>(with no arguments). This GNU program (recursively) converts
1615 <filename><constant>$(FPTOOLS_TOP)</constant>/configure.ac</filename> and
1616 <filename><constant>$(FPTOOLS_TOP)</constant>/aclocal.m4</filename>
1617 to a shell script called
1618 <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
1619 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
1620 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
1621 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
1622 a message like "No rule to make target 'mk/config.h.in'".
1625 <para>Some projects, including GHC, have their own configure script.
1626 <command>autoreconf</command> takes care of that, too, so all you have
1627 to do is calling <command>autoreconf</command> in the top-level directory
1628 <constant>$(FPTOOLS_TOP)</constant>.</para>
1630 <para>These steps are completely platform-independent; they just mean
1631 that the human-written files (<filename>configure.ac</filename> and
1632 <filename>aclocal.m4</filename>) can be short, although the resulting
1633 files (the <command>configure</command> shell scripts and the C header
1634 template <filename>mk/config.h.in</filename>) are long.</para>
1639 <term>Step 2: system configuration.</term>
1641 <para>Runs the newly-created <command>configure</command>
1642 script, thus:</para>
1645 ./configure <optional><parameter>args</parameter></optional>
1648 <para><command>configure</command>'s mission is to scurry
1649 round your computer working out what architecture it has,
1650 what operating system, whether it has the
1651 <Function>vfork</Function> system call, where
1652 <command>tar</command> is kept, whether
1653 <command>gcc</command> is available, where various obscure
1654 <literal>#include</literal> files are, whether it's a
1655 leap year, and what the systems manager had for lunch. It
1656 communicates these snippets of information in two
1663 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1665 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1666 substituting for things between
1667 “<literal>@</literal>” brackets. So,
1668 “<literal>@HaveGcc@</literal>” will be
1669 replaced by “<literal>YES</literal>” or
1670 “<literal>NO</literal>” depending on what
1671 <command>configure</command> finds.
1672 <filename>mk/config.mk</filename> is included by every
1673 Makefile (directly or indirectly), so the
1674 configuration information is thereby communicated to
1675 all Makefiles.</para>
1679 <para> It translates
1680 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1682 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1683 The latter is <literal>#include</literal>d by
1684 various C programs, which can thereby make use of
1685 configuration information.</para>
1689 <para><command>configure</command> takes some optional
1690 arguments. Use <literal>./configure --help</literal> to
1691 get a list of the available arguments. Here are some of
1692 the ones you might need:</para>
1696 <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
1697 <indexterm><primary><literal>--with-ghc</literal></primary>
1700 <para>Specifies the path to an installed GHC which
1701 you would like to use. This compiler will be used
1702 for compiling GHC-specific code (eg. GHC itself).
1703 This option <emphasis>cannot</emphasis> be specified
1704 using <filename>build.mk</filename> (see later),
1705 because <command>configure</command> needs to
1706 auto-detect the version of GHC you're using. The
1707 default is to look for a compiler named
1708 <literal>ghc</literal> in your path.</para>
1713 <term><literal>--with-hc=<parameter>path</parameter></literal></term>
1714 <indexterm><primary><literal>--with-hc</literal></primary>
1717 <para>Specifies the path to any installed Haskell
1718 compiler. This compiler will be used for compiling
1719 generic Haskell code. The default is to use
1720 <literal>ghc</literal>.</para>
1725 <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
1726 <indexterm><primary><literal>--with-gcc</literal></primary>
1729 <para>Specifies the path to the installed GCC. This
1730 compiler will be used to compile all C files,
1731 <emphasis>except</emphasis> any generated by the
1732 installed Haskell compiler, which will have its own
1733 idea of which C compiler (if any) to use. The
1734 default is to use <literal>gcc</literal>.</para>
1742 <term>Step 3: build configuration.</term>
1744 <para>Next, you say how this build of
1745 <literal>fptools</literal> is to differ from the standard
1746 defaults by creating a new file
1747 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1748 <emphasis>in the build tree</emphasis>. This file is the
1749 one and only file you edit in the build tree, precisely
1750 because it says how this build differs from the source.
1751 (Just in case your build tree does die, you might want to
1752 keep a private directory of <filename>build.mk</filename>
1753 files, and use a symbolic link in each build tree to point
1754 to the appropriate one.) So
1755 <filename>mk/build.mk</filename> never exists in the
1756 source tree—you create one in each build tree from
1757 the template. We'll discuss what to put in it
1763 <para>And that's it for configuration. Simple, eh?</para>
1765 <para>What do you put in your build-specific configuration file
1766 <filename>mk/build.mk</filename>? <emphasis>For almost all
1767 purposes all you will do is put make variable definitions that
1768 override those in</emphasis>
1769 <filename>mk/config.mk.in</filename>. The whole point of
1770 <filename>mk/config.mk.in</filename>—and its derived
1771 counterpart <filename>mk/config.mk</filename>—is to define
1772 the build configuration. It is heavily commented, as you will
1773 see if you look at it. So generally, what you do is look at
1774 <filename>mk/config.mk.in</filename>, and add definitions in
1775 <filename>mk/build.mk</filename> that override any of the
1776 <filename>config.mk</filename> definitions that you want to
1777 change. (The override occurs because the main boilerplate file,
1778 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1779 includes <filename>build.mk</filename> after
1780 <filename>config.mk</filename>.)</para>
1782 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1783 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1785 <para>For example, <filename>config.mk.in</filename> contains
1786 the definition:</para>
1789 GhcHcOpts=-O -Rghc-timing
1792 <para>The accompanying comment explains that this is the list of
1793 flags passed to GHC when building GHC itself. For doing
1794 development, it is wise to add <literal>-DDEBUG</literal>, to
1795 enable debugging code. So you would add the following to
1796 <filename>build.mk</filename>:</para>
1798 <para>or, if you prefer,</para>
1801 GhcHcOpts += -DDEBUG
1804 <para>GNU <command>make</command> allows existing definitions to
1805 have new text appended using the “<literal>+=</literal>”
1806 operator, which is quite a convenient feature.)</para>
1808 <para>If you want to remove the <literal>-O</literal> as well (a
1809 good idea when developing, because the turn-around cycle gets a
1810 lot quicker), you can just override
1811 <literal>GhcLibHcOpts</literal> altogether:</para>
1814 GhcHcOpts=-DDEBUG -Rghc-timing
1817 <para>When reading <filename>config.mk.in</filename>, remember
1818 that anything between “@...@” signs is going to be substituted
1819 by <command>configure</command> later. You
1820 <emphasis>can</emphasis> override the resulting definition if
1821 you want, but you need to be a bit surer what you are doing.
1822 For example, there's a line that says:</para>
1828 <para>This defines the Make variables <constant>TAR</constant>
1829 to the pathname for a <command>tar</command> that
1830 <command>configure</command> finds somewhere. If you have your
1831 own pet <command>tar</command> you want to use instead, that's
1832 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1838 <para>You do not <emphasis>have</emphasis> to have a
1839 <filename>mk/build.mk</filename> file at all; if you don't,
1840 you'll get all the default settings from
1841 <filename>mk/config.mk.in</filename>.</para>
1843 <para>You can also use <filename>build.mk</filename> to override
1844 anything that <command>configure</command> got wrong. One place
1845 where this happens often is with the definition of
1846 <constant>FPTOOLS_TOP_ABS</constant>: this
1847 variable is supposed to be the canonical path to the top of your
1848 source tree, but if your system uses an automounter then the
1849 correct directory is hard to find automatically. If you find
1850 that <command>configure</command> has got it wrong, just put the
1851 correct definition in <filename>build.mk</filename>.</para>
1855 <sect2 id="sec-storysofar">
1856 <title>The story so far</title>
1858 <para>Let's summarise the steps you need to carry to get
1859 yourself a fully-configured build tree from scratch.</para>
1863 <para> Get your source tree from somewhere (CVS repository
1864 or source distribution). Say you call the root directory
1865 <filename>myfptools</filename> (it does not have to be
1866 called <filename>fptools</filename>). Make sure that you
1867 have the essential files (see <XRef
1868 LinkEnd="sec-source-tree">).</para>
1873 <para>(Optional) Use <command>lndir</command> or
1874 <command>mkshadowdir</command> to create a build tree.</para>
1878 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1881 <para>(N.B. <command>mkshadowdir</command>'s first argument
1882 is taken relative to its second.) You probably want to give
1883 the build tree a name that suggests its main defining
1884 characteristic (in your mind at least), in case you later
1889 <para>Change directory to the build tree. Everything is
1890 going to happen there now.</para>
1893 $ cd /scratch/joe-bloggs/myfptools-sun4
1899 <para>Prepare for system configuration:</para>
1905 <para>(You can skip this step if you are starting from a
1906 source distribution, and you already have
1907 <filename>configure</filename> and
1908 <filename>mk/config.h.in</filename>.)</para>
1912 <para>Do system configuration:</para>
1918 <para>Don't forget to check whether you need to add any
1919 arguments to <literal>configure</literal>; for example, a
1920 common requirement is to specify which GHC to use with
1921 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1925 <para>Create the file <filename>mk/build.mk</filename>,
1926 adding definitions for your desired configuration
1935 <para>You can make subsequent changes to
1936 <filename>mk/build.mk</filename> as often as you like. You do
1937 not have to run any further configuration programs to make these
1938 changes take effect. In theory you should, however, say
1939 <command>gmake clean</command>, <command>gmake all</command>,
1940 because configuration option changes could affect
1941 anything—but in practice you are likely to know what's
1946 <title>Making things</title>
1948 <para>At this point you have made yourself a fully-configured
1949 build tree, so you are ready to start building real
1952 <para>The first thing you need to know is that <emphasis>you
1953 must use GNU <command>make</command>, usually called
1954 <command>gmake</command>, not standard Unix
1955 <command>make</command></emphasis>. If you use standard Unix
1956 <command>make</command> you will get all sorts of error messages
1957 (but no damage) because the <literal>fptools</literal>
1958 <command>Makefiles</command> use GNU <command>make</command>'s
1959 facilities extensively.</para>
1961 <para>To just build the whole thing, <command>cd</command> to
1962 the top of your <literal>fptools</literal> tree and type
1963 <command>gmake</command>. This will prepare the tree and build
1964 the various projects in the correct order.</para>
1967 <sect2 id="sec-bootstrapping">
1968 <title>Bootstrapping GHC</title>
1970 <para>GHC requires a 2-stage bootstrap in order to provide
1971 full functionality, including GHCi. By a 2-stage bootstrap, we
1972 mean that the compiler is built once using the installed GHC,
1973 and then again using the compiler built in the first stage. You
1974 can also build a stage 3 compiler, but this normally isn't
1975 necessary except to verify that the stage 2 compiler is working
1978 <para>Note that when doing a bootstrap, the stage 1 compiler
1979 must be built, followed by the runtime system and libraries, and
1980 then the stage 2 compiler. The correct ordering is implemented
1981 by the top-level fptools <filename>Makefile</filename>, so if
1982 you want everything to work automatically it's best to start
1983 <command>make</command> from the top of the tree. When building
1984 GHC, the top-level fptools <filename>Makefile</filename> is set
1985 up to do a 2-stage bootstrap by default (when you say
1986 <command>make</command>). Some other targets it supports
1993 <para>Build everything as normal, including the stage 1
2001 <para>Build the stage 2 compiler only.</para>
2008 <para>Build the stage 3 compiler only.</para>
2013 <term>bootstrap</term> <term>bootstrap2</term>
2015 <para>Build stage 1 followed by stage 2.</para>
2020 <term>bootstrap3</term>
2022 <para>Build stages 1, 2 and 3.</para>
2027 <term>install</term>
2029 <para>Install everything, including the compiler built in
2030 stage 2. To override the stage, say <literal>make install
2031 stage=<replaceable>n</replaceable></literal> where
2032 <replaceable>n</replaceable> is the stage to install.</para>
2037 <para>The top-level <filename>Makefile</filename> also arranges
2038 to do the appropriate <literal>make boot</literal> steps (see
2039 below) before actually building anything.</para>
2041 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2042 and <literal>stage3</literal> targets also work in the
2043 <literal>ghc/compiler</literal> directory, but don't forget that
2044 each stage requires its own <literal>make boot</literal> step:
2045 for example, you must do</para>
2047 <screen>$ make boot stage=2</screen>
2049 <para>before <literal>make stage2</literal> in
2050 <literal>ghc/compiler</literal>.</para>
2053 <sect2 id="sec-standard-targets">
2054 <title>Standard Targets</title>
2055 <indexterm><primary>targets, standard makefile</primary></indexterm>
2056 <indexterm><primary>makefile targets</primary></indexterm>
2058 <para>In any directory you should be able to make the following:</para>
2062 <term><literal>boot</literal></term>
2064 <para>does the one-off preparation required to get ready
2065 for the real work. Notably, it does <command>gmake
2066 depend</command> in all directories that contain programs.
2067 It also builds the necessary tools for compilation to
2070 <para>Invoking the <literal>boot</literal> target
2071 explicitly is not normally necessary. From the top-level
2072 <literal>fptools</literal> directory, invoking
2073 <literal>gmake</literal> causes <literal>gmake boot
2074 all</literal> to be invoked in each of the project
2075 subdirectories, in the order specified by
2076 <literal>$(AllTargets)</literal> in
2077 <literal>config.mk</literal>.</para>
2079 <para>If you're working in a subdirectory somewhere and
2080 need to update the dependencies, <literal>gmake
2081 boot</literal> is a good way to do it.</para>
2086 <term><literal>all</literal></term>
2088 <para>makes all the final target(s) for this Makefile.
2089 Depending on which directory you are in a “final
2090 target” may be an executable program, a library
2091 archive, a shell script, or a Postscript file. Typing
2092 <command>gmake</command> alone is generally the same as
2093 typing <command>gmake all</command>.</para>
2098 <term><literal>install</literal></term>
2100 <para>installs the things built by <literal>all</literal>
2101 (except for the documentation). Where does it install
2102 them? That is specified by
2103 <filename>mk/config.mk.in</filename>; you can override it
2104 in <filename>mk/build.mk</filename>, or by running
2105 <command>configure</command> with command-line arguments
2106 like <literal>--bindir=/home/simonpj/bin</literal>; see
2107 <literal>./configure --help</literal> for the full
2113 <term><literal>install-docs</literal></term>
2115 <para>installs the documentation. Otherwise behaves just
2116 like <literal>install</literal>.</para>
2121 <term><literal>uninstall</literal></term>
2123 <para>reverses the effect of
2124 <literal>install</literal>.</para>
2129 <term><literal>clean</literal></term>
2131 <para>Delete all files from the current directory that are
2132 normally created by building the program. Don't delete
2133 the files that record the configuration, or files
2134 generated by <command>gmake boot</command>. Also preserve
2135 files that could be made by building, but normally aren't
2136 because the distribution comes with them.</para>
2141 <term><literal>distclean</literal></term>
2143 <para>Delete all files from the current directory that are
2144 created by configuring or building the program. If you
2145 have unpacked the source and built the program without
2146 creating any other files, <literal>make
2147 distclean</literal> should leave only the files that were
2148 in the distribution.</para>
2153 <term><literal>mostlyclean</literal></term>
2155 <para>Like <literal>clean</literal>, but may refrain from
2156 deleting a few files that people normally don't want to
2162 <term><literal>maintainer-clean</literal></term>
2164 <para>Delete everything from the current directory that
2165 can be reconstructed with this Makefile. This typically
2166 includes everything deleted by
2167 <literal>distclean</literal>, plus more: C source files
2168 produced by Bison, tags tables, Info files, and so
2171 <para>One exception, however: <literal>make
2172 maintainer-clean</literal> should not delete
2173 <filename>configure</filename> even if
2174 <filename>configure</filename> can be remade using a rule
2175 in the <filename>Makefile</filename>. More generally,
2176 <literal>make maintainer-clean</literal> should not delete
2177 anything that needs to exist in order to run
2178 <filename>configure</filename> and then begin to build the
2184 <term><literal>check</literal></term>
2186 <para>run the test suite.</para>
2191 <para>All of these standard targets automatically recurse into
2192 sub-directories. Certain other standard targets do not:</para>
2196 <term><literal>configure</literal></term>
2198 <para>is only available in the root directory
2199 <constant>$(FPTOOLS_TOP)</constant>; it has
2200 been discussed in <XRef
2201 LinkEnd="sec-build-config">.</para>
2206 <term><literal>depend</literal></term>
2208 <para>make a <filename>.depend</filename> file in each
2209 directory that needs it. This <filename>.depend</filename>
2210 file contains mechanically-generated dependency
2211 information; for example, suppose a directory contains a
2212 Haskell source module <filename>Foo.lhs</filename> which
2213 imports another module <literal>Baz</literal>. Then the
2214 generated <filename>.depend</filename> file will contain
2215 the dependency:</para>
2221 <para>which says that the object file
2222 <filename>Foo.o</filename> depends on the interface file
2223 <filename>Baz.hi</filename> generated by compiling module
2224 <literal>Baz</literal>. The <filename>.depend</filename>
2225 file is automatically included by every Makefile.</para>
2230 <term><literal>binary-dist</literal></term>
2232 <para>make a binary distribution. This is the target we
2233 use to build the binary distributions of GHC and
2239 <term><literal>dist</literal></term>
2241 <para>make a source distribution. Note that this target
2242 does “make distclean” as part of its work;
2243 don't use it if you want to keep what you've built.</para>
2248 <para>Most <filename>Makefile</filename>s have targets other
2249 than these. You can discover them by looking in the
2250 <filename>Makefile</filename> itself.</para>
2254 <title>Using a project from the build tree</title>
2256 <para>If you want to build GHC (say) and just use it direct from
2257 the build tree without doing <literal>make install</literal>
2258 first, you can run the in-place driver script:
2259 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2261 <para> Do <emphasis>NOT</emphasis> use
2262 <filename>ghc/compiler/ghc</filename>, or
2263 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2264 scripts intended for installation, and contain hard-wired paths
2265 to the installed libraries, rather than the libraries in the
2268 <para>Happy can similarly be run from the build tree, using
2269 <filename>happy/src/happy-inplace</filename>, and similarly for
2270 Alex and Haddock.</para>
2274 <title>Fast Making</title>
2276 <indexterm><primary>fastmake</primary></indexterm>
2277 <indexterm><primary>dependencies, omitting</primary></indexterm>
2278 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2280 <para>Sometimes the dependencies get in the way: if you've made
2281 a small change to one file, and you're absolutely sure that it
2282 won't affect anything else, but you know that
2283 <command>make</command> is going to rebuild everything anyway,
2284 the following hack may be useful:</para>
2290 <para>This tells the make system to ignore dependencies and just
2291 build what you tell it to. In other words, it's equivalent to
2292 temporarily removing the <filename>.depend</filename> file in
2293 the current directory (where <command>mkdependHS</command> and
2294 friends store their dependency information).</para>
2296 <para>A bit of history: GHC used to come with a
2297 <command>fastmake</command> script that did the above job, but
2298 GNU make provides the features we need to do it without
2299 resorting to a script. Also, we've found that fastmaking is
2300 less useful since the advent of GHC's recompilation checker (see
2301 the User's Guide section on "Separate Compilation").</para>
2305 <sect1 id="sec-makefile-arch">
2306 <title>The <filename>Makefile</filename> architecture</title>
2307 <indexterm><primary>makefile architecture</primary></indexterm>
2309 <para><command>make</command> is great if everything
2310 works—you type <command>gmake install</command> and lo! the
2311 right things get compiled and installed in the right places. Our
2312 goal is to make this happen often, but somehow it often doesn't;
2313 instead some weird error message eventually emerges from the
2314 bowels of a directory you didn't know existed.</para>
2316 <para>The purpose of this section is to give you a road-map to
2317 help you figure out what is going right and what is going
2321 <title>Debugging</title>
2323 <para>Debugging <filename>Makefile</filename>s is something of a
2324 black art, but here's a couple of tricks that we find
2325 particularly useful. The following command allows you to see
2326 the contents of any make variable in the context of the current
2327 <filename>Makefile</filename>:</para>
2329 <screen>$ make show VALUE=HS_SRCS</screen>
2331 <para>where you can replace <literal>HS_SRCS</literal> with the
2332 name of any variable you wish to see the value of.</para>
2334 <para>GNU make has a <option>-d</option> option which generates
2335 a dump of the decision procedure used to arrive at a conclusion
2336 about which files should be recompiled. Sometimes useful for
2337 tracking down problems with superfluous or missing
2338 recompilations.</para>
2342 <title>A small project</title>
2344 <para>To get started, let us look at the
2345 <filename>Makefile</filename> for an imaginary small
2346 <literal>fptools</literal> project, <literal>small</literal>.
2347 Each project in <literal>fptools</literal> has its own directory
2348 in <constant>FPTOOLS_TOP</constant>, so the
2349 <literal>small</literal> project will have its own directory
2350 <constant>FPOOLS_TOP/small/</constant>. Inside the
2351 <filename>small/</filename> directory there will be a
2352 <filename>Makefile</filename>, looking something like
2355 <indexterm><primary>Makefile, minimal</primary></indexterm>
2358 # Makefile for fptools project "small"
2361 include $(TOP)/mk/boilerplate.mk
2363 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2366 include $(TOP)/target.mk
2369 <para>this <filename>Makefile</filename> has three
2374 <para>The first section includes
2377 One of the most important
2378 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2379 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2384 a file of “boilerplate” code from the level
2385 above (which in this case will be
2386 <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2387 As its name suggests, <filename>boilerplate.mk</filename>
2388 consists of a large quantity of standard
2389 <filename>Makefile</filename> code. We discuss this
2390 boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
2391 <indexterm><primary>include, directive in
2392 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2393 inclusion</primary></indexterm></para>
2395 <para>Before the <literal>include</literal> statement, you
2396 must define the <command>make</command> variable
2397 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2398 to be the directory containing the <filename>mk</filename>
2399 directory in which the <filename>boilerplate.mk</filename>
2400 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2403 include ../mk/boilerplate.mk # NO NO NO
2407 <para>Why? Because the <filename>boilerplate.mk</filename>
2408 file needs to know where it is, so that it can, in turn,
2409 <literal>include</literal> other files. (Unfortunately,
2410 when an <literal>include</literal>d file does an
2411 <literal>include</literal>, the filename is treated relative
2412 to the directory in which <command>gmake</command> is being
2413 run, not the directory in which the
2414 <literal>include</literal>d sits.) In general,
2415 <emphasis>every file <filename>foo.mk</filename> assumes
2417 <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
2418 refers to itself.</emphasis> It is up to the
2419 <filename>Makefile</filename> doing the
2420 <literal>include</literal> to ensure this is the case.</para>
2422 <para>Files intended for inclusion in other
2423 <filename>Makefile</filename>s are written to have the
2424 following property: <emphasis>after
2425 <filename>foo.mk</filename> is <literal>include</literal>d,
2426 it leaves <constant>TOP</constant> containing the same value
2427 as it had just before the <literal>include</literal>
2428 statement</emphasis>. In our example, this invariant
2429 guarantees that the <literal>include</literal> for
2430 <filename>target.mk</filename> will look in the same
2431 directory as that for <filename>boilerplate.mk</filename>.</para>
2435 <para> The second section defines the following standard
2436 <command>make</command> variables:
2437 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2438 (the source files from which is to be built), and
2439 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2440 (the executable binary to be built). We will discuss in
2441 more detail what the “standard variables” are,
2442 and how they affect what happens, in <XRef
2443 LinkEnd="sec-targets">.</para>
2445 <para>The definition for <constant>SRCS</constant> uses the
2446 useful GNU <command>make</command> construct
2447 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2448 which expands to a list of all the files matching the
2449 pattern <literal>pat</literal> in the current directory. In
2450 this example, <constant>SRCS</constant> is set to the list
2451 of all the <filename>.lhs</filename> and
2452 <filename>.c</filename> files in the directory. (Let's
2453 suppose there is one of each, <filename>Foo.lhs</filename>
2454 and <filename>Baz.c</filename>.)</para>
2458 <para>The last section includes a second file of standard
2460 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2461 It contains the rules that tell <command>gmake</command> how
2462 to make the standard targets (<Xref
2463 LinkEnd="sec-standard-targets">). Why, you ask, can't this
2464 standard code be part of
2465 <filename>boilerplate.mk</filename>? Good question. We
2466 discuss the reason later, in <Xref
2467 LinkEnd="sec-boiler-arch">.</para>
2469 <para>You do not <emphasis>have</emphasis> to
2470 <literal>include</literal> the
2471 <filename>target.mk</filename> file. Instead, you can write
2472 rules of your own for all the standard targets. Usually,
2473 though, you will find quite a big payoff from using the
2474 canned rules in <filename>target.mk</filename>; the price
2475 tag is that you have to understand what canned rules get
2476 enabled, and what they do (<Xref
2477 LinkEnd="sec-targets">).</para>
2481 <para>In our example <filename>Makefile</filename>, most of the
2482 work is done by the two <literal>include</literal>d files. When
2483 you say <command>gmake all</command>, the following things
2488 <para><command>gmake</command> figures out that the object
2489 files are <filename>Foo.o</filename> and
2490 <filename>Baz.o</filename>.</para>
2494 <para>It uses a boilerplate pattern rule to compile
2495 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2496 using a Haskell compiler. (Which one? That is set in the
2497 build configuration.)</para>
2501 <para>It uses another standard pattern rule to compile
2502 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2503 using a C compiler. (Ditto.)</para>
2507 <para>It links the resulting <filename>.o</filename> files
2508 together to make <literal>small</literal>, using the Haskell
2509 compiler to do the link step. (Why not use
2510 <command>ld</command>? Because the Haskell compiler knows
2511 what standard libraries to link in. How did
2512 <command>gmake</command> know to use the Haskell compiler to
2513 do the link, rather than the C compiler? Because we set the
2514 variable <constant>HS_PROG</constant> rather than
2515 <constant>C_PROG</constant>.)</para>
2519 <para>All <filename>Makefile</filename>s should follow the above
2520 three-section format.</para>
2524 <title>A larger project</title>
2526 <para>Larger projects are usually structured into a number of
2527 sub-directories, each of which has its own
2528 <filename>Makefile</filename>. (In very large projects, this
2529 sub-structure might be iterated recursively, though that is
2530 rare.) To give you the idea, here's part of the directory
2531 structure for the (rather large) GHC project:</para>
2541 ...source files for documentation...
2544 ...source files for driver...
2547 parser/...source files for parser...
2548 renamer/...source files for renamer...
2552 <para>The sub-directories <filename>docs</filename>,
2553 <filename>driver</filename>, <filename>compiler</filename>, and
2554 so on, each contains a sub-component of GHC, and each has its
2555 own <filename>Makefile</filename>. There must also be a
2556 <filename>Makefile</filename> in
2557 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
2558 It does most of its work by recursively invoking
2559 <command>gmake</command> on the <filename>Makefile</filename>s
2560 in the sub-directories. We say that
2561 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2562 <filename>Makefile</filename></emphasis>, because it does little
2563 except organise its children, while the
2564 <filename>Makefile</filename>s in the sub-directories are all
2565 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2566 principle the sub-directories might themselves contain a
2567 non-leaf <filename>Makefile</filename> and several
2568 sub-sub-directories, but that does not happen in GHC.)</para>
2570 <para>The <filename>Makefile</filename> in
2571 <filename>ghc/compiler</filename> is considered a leaf
2572 <filename>Makefile</filename> even though the
2573 <filename>ghc/compiler</filename> has sub-directories, because
2574 these sub-directories do not themselves have
2575 <filename>Makefile</filename>s in them. They are just used to
2576 structure the collection of modules that make up GHC, but all
2577 are managed by the single <filename>Makefile</filename> in
2578 <filename>ghc/compiler</filename>.</para>
2580 <para>You will notice that <filename>ghc/</filename> also
2581 contains a directory <filename>ghc/mk/</filename>. It contains
2582 GHC-specific <filename>Makefile</filename> boilerplate code.
2583 More precisely:</para>
2587 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2588 at the top of <filename>ghc/Makefile</filename>, and of all
2589 the leaf <filename>Makefile</filename>s in the
2590 sub-directories. It in turn <literal>include</literal>s the
2591 main boilerplate file
2592 <filename>mk/boilerplate.mk</filename>.</para>
2596 <para><filename>ghc/mk/target.mk</filename> is
2597 <literal>include</literal>d at the bottom of
2598 <filename>ghc/Makefile</filename>, and of all the leaf
2599 <filename>Makefile</filename>s in the sub-directories. It
2600 in turn <literal>include</literal>s the file
2601 <filename>mk/target.mk</filename>.</para>
2605 <para>So these two files are the place to look for GHC-wide
2606 customisation of the standard boilerplate.</para>
2609 <sect2 id="sec-boiler-arch">
2610 <title>Boilerplate architecture</title>
2611 <indexterm><primary>boilerplate architecture</primary></indexterm>
2613 <para>Every <filename>Makefile</filename> includes a
2614 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2615 file at the top, and
2616 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2617 file at the bottom. In this section we discuss what is in these
2618 files, and why there have to be two of them. In general:</para>
2622 <para><filename>boilerplate.mk</filename> consists of:</para>
2626 <para><emphasis>Definitions of millions of
2627 <command>make</command> variables</emphasis> that
2628 collectively specify the build configuration. Examples:
2629 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2630 the options to feed to the Haskell compiler;
2631 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2632 the sub-directories to enable within the
2633 <literal>nofib</literal> project;
2634 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2635 the name of the Haskell compiler to use when compiling
2636 GHC in the <literal>ghc</literal> project.</para>
2640 <para><emphasis>Standard pattern rules</emphasis> that
2641 tell <command>gmake</command> how to construct one file
2642 from another.</para>
2646 <para><filename>boilerplate.mk</filename> needs to be
2647 <literal>include</literal>d at the <emphasis>top</emphasis>
2648 of each <filename>Makefile</filename>, so that the user can
2649 replace the boilerplate definitions or pattern rules by
2650 simply giving a new definition or pattern rule in the
2651 <filename>Makefile</filename>. <command>gmake</command>
2652 simply takes the last definition as the definitive one.</para>
2654 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2655 definitions, it is also quite common to
2656 <emphasis>augment</emphasis> them. For example, a
2657 <filename>Makefile</filename> might say:</para>
2663 <para>thereby adding “<option>-O</option>” to
2665 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2669 <para><filename>target.mk</filename> contains
2670 <command>make</command> rules for the standard targets
2671 described in <Xref LinkEnd="sec-standard-targets">. These
2672 rules are selectively included, depending on the setting of
2673 certain <command>make</command> variables. These variables
2674 are usually set in the middle section of the
2675 <filename>Makefile</filename> between the two
2676 <literal>include</literal>s.</para>
2678 <para><filename>target.mk</filename> must be included at the
2679 end (rather than being part of
2680 <filename>boilerplate.mk</filename>) for several tiresome
2686 <para><command>gmake</command> commits target and
2687 dependency lists earlier than it should. For example,
2688 <FIlename>target.mk</FIlename> has a rule that looks
2692 $(HS_PROG) : $(OBJS)
2693 $(HC) $(LD_OPTS) $< -o $@
2696 <para>If this rule was in
2697 <filename>boilerplate.mk</filename> then
2698 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2700 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2701 would not have their final values at the moment
2702 <command>gmake</command> encountered the rule. Alas,
2703 <command>gmake</command> takes a snapshot of their
2704 current values, and wires that snapshot into the rule.
2705 (In contrast, the commands executed when the rule
2706 “fires” are only substituted at the moment
2707 of firing.) So, the rule must follow the definitions
2708 given in the <filename>Makefile</filename> itself.</para>
2712 <para>Unlike pattern rules, ordinary rules cannot be
2713 overriden or replaced by subsequent rules for the same
2714 target (at least, not without an error message).
2715 Including ordinary rules in
2716 <filename>boilerplate.mk</filename> would prevent the
2717 user from writing rules for specific targets in specific
2722 <para>There are a couple of other reasons I've
2723 forgotten, but it doesn't matter too much.</para>
2730 <sect2 id="sec-boiler">
2731 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2732 <indexterm><primary>boilerplate.mk</primary></indexterm>
2734 <para>If you look at
2735 <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
2736 you will find that it consists of the following sections, each
2737 held in a separate file:</para>
2741 <term><filename>config.mk</filename></term>
2742 <indexterm><primary>config.mk</primary></indexterm>
2744 <para>is the build configuration file we discussed at
2745 length in <Xref LinkEnd="sec-build-config">.</para>
2750 <term><filename>paths.mk</filename></term>
2751 <indexterm><primary>paths.mk</primary></indexterm>
2753 <para>defines <command>make</command> variables for
2754 pathnames and file lists. This file contains code for
2755 automatically compiling lists of source files and deriving
2756 lists of object files from those. The results can be
2757 overriden in the <filename>Makefile</filename>, but in
2758 most cases the automatic setup should do the right
2761 <para>The following variables may be set in the
2762 <filename>Makefile</filename> to affect how the automatic
2763 source file search is done:</para>
2767 <term><literal>ALL_DIRS</literal></term>
2768 <indexterm><primary><literal>ALL_DIRS</literal></primary>
2771 <para>Set to a list of directories to search in
2772 addition to the current directory for source
2778 <term><literal>EXCLUDE_SRCS</literal></term>
2779 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2782 <para>Set to a list of source files (relative to the
2783 current directory) to omit from the automatic
2784 search. The source searching machinery is clever
2785 enough to know that if you exclude a source file
2786 from which other sources are derived, then the
2787 derived sources should also be excluded. For
2788 example, if you set <literal>EXCLUDED_SRCS</literal>
2789 to include <filename>Foo.y</filename>, then
2790 <filename>Foo.hs</filename> will also be
2796 <term><literal>EXTRA_SRCS</literal></term>
2797 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2800 <para>Set to a list of extra source files (perhaps
2801 in directories not listed in
2802 <literal>ALL_DIRS</literal>) that should be
2808 <para>The results of the automatic source file search are
2809 placed in the following make variables:</para>
2813 <term><literal>SRCS</literal></term>
2814 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2816 <para>All source files found, sorted and without
2817 duplicates, including those which might not exist
2818 yet but will be derived from other existing sources.
2819 <literal>SRCS</literal> <emphasis>can</emphasis> be
2820 overriden if necessary, in which case the variables
2821 below will follow suit.</para>
2826 <term><literal>HS_SRCS</literal></term>
2827 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2829 <para>all Haskell source files in the current
2830 directory, including those derived from other source
2831 files (eg. Happy sources also give rise to Haskell
2837 <term><literal>HS_OBJS</literal></term>
2838 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2840 <para>Object files derived from
2841 <literal>HS_SRCS</literal>.</para>
2846 <term><literal>HS_IFACES</literal></term>
2847 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2849 <para>Interface files (<literal>.hi</literal> files)
2850 derived from <literal>HS_SRCS</literal>.</para>
2855 <term><literal>C_SRCS</literal></term>
2856 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2858 <para>All C source files found.</para>
2863 <term><literal>C_OBJS</literal></term>
2864 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2866 <para>Object files derived from
2867 <literal>C_SRCS</literal>.</para>
2872 <term><literal>SCRIPT_SRCS</literal></term>
2873 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2875 <para>All script source files found
2876 (<literal>.lprl</literal> files).</para>
2881 <term><literal>SCRIPT_OBJS</literal></term>
2882 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2884 <para><quote>object</quote> files derived from
2885 <literal>SCRIPT_SRCS</literal>
2886 (<literal>.prl</literal> files).</para>
2891 <term><literal>HSC_SRCS</literal></term>
2892 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2894 <para>All <literal>hsc2hs</literal> source files
2895 (<literal>.hsc</literal> files).</para>
2900 <term><literal>HAPPY_SRCS</literal></term>
2901 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2903 <para>All <literal>happy</literal> source files
2904 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2909 <term><literal>OBJS</literal></term>
2910 <indexterm><primary>OBJS</primary></indexterm>
2912 <para>the concatenation of
2913 <literal>$(HS_OBJS)</literal>,
2914 <literal>$(C_OBJS)</literal>, and
2915 <literal>$(SCRIPT_OBJS)</literal>.</para>
2920 <para>Any or all of these definitions can easily be
2921 overriden by giving new definitions in your
2922 <filename>Makefile</filename>.</para>
2924 <para>What, exactly, does <filename>paths.mk</filename>
2925 consider a <quote>source file</quote> to be? It's based
2926 on the file's suffix (e.g. <filename>.hs</filename>,
2927 <filename>.lhs</filename>, <filename>.c</filename>,
2928 <filename>.hy</filename>, etc), but this is the kind of
2929 detail that changes, so rather than enumerate the source
2930 suffices here the best thing to do is to look in
2931 <filename>paths.mk</filename>.</para>
2936 <term><filename>opts.mk</filename></term>
2937 <indexterm><primary>opts.mk</primary></indexterm>
2939 <para>defines <command>make</command> variables for option
2940 strings to pass to each program. For example, it defines
2941 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2942 the option strings to pass to the Haskell compiler. See
2943 <Xref LinkEnd="sec-suffix">.</para>
2948 <term><filename>suffix.mk</filename></term>
2949 <indexterm><primary>suffix.mk</primary></indexterm>
2951 <para>defines standard pattern rules—see <Xref
2952 LinkEnd="sec-suffix">.</para>
2957 <para>Any of the variables and pattern rules defined by the
2958 boilerplate file can easily be overridden in any particular
2959 <filename>Makefile</filename>, because the boilerplate
2960 <literal>include</literal> comes first. Definitions after this
2961 <literal>include</literal> directive simply override the default
2962 ones in <filename>boilerplate.mk</filename>.</para>
2965 <sect2 id="sec-suffix">
2966 <title>Pattern rules and options</title>
2967 <indexterm><primary>Pattern rules</primary></indexterm>
2970 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2971 defines standard <emphasis>pattern rules</emphasis> that say how
2972 to build one kind of file from another, for example, how to
2973 build a <filename>.o</filename> file from a
2974 <filename>.c</filename> file. (GNU <command>make</command>'s
2975 <emphasis>pattern rules</emphasis> are more powerful and easier
2976 to use than Unix <command>make</command>'s <emphasis>suffix
2977 rules</emphasis>.)</para>
2979 <para>Almost all the rules look something like this:</para>
2984 $(CC) $(CC_OPTS) -c $< -o $@
2987 <para>Here's how to understand the rule. It says that
2988 <emphasis>something</emphasis><filename>.o</filename> (say
2989 <filename>Foo.o</filename>) can be built from
2990 <emphasis>something</emphasis><filename>.c</filename>
2991 (<filename>Foo.c</filename>), by invoking the C compiler (path
2992 name held in <constant>$(CC)</constant>), passing to it
2993 the options <constant>$(CC_OPTS)</constant> and
2994 the rule's dependent file of the rule
2995 <literal>$<</literal> (<filename>Foo.c</filename> in
2996 this case), and putting the result in the rule's target
2997 <literal>$@</literal> (<filename>Foo.o</filename> in this
3000 <para>Every program is held in a <command>make</command>
3001 variable defined in <filename>mk/config.mk</filename>—look
3002 in <filename>mk/config.mk</filename> for the complete list. One
3003 important one is the Haskell compiler, which is called
3004 <constant>$(HC)</constant>.</para>
3006 <para>Every program's options are are held in a
3007 <command>make</command> variables called
3008 <constant><prog>_OPTS</constant>. the
3009 <constant><prog>_OPTS</constant> variables are
3010 defined in <filename>mk/opts.mk</filename>. Almost all of them
3011 are defined like this:</para>
3014 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
3017 <para>The four variables from which
3018 <constant>CC_OPTS</constant> is built have the following
3023 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
3025 <para>options passed to all C compilations.</para>
3030 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
3032 <para>options passed to C compilations for way
3033 <literal><way></literal>. For example,
3034 <constant>WAY_mp_CC_OPTS</constant>
3035 gives options to pass to the C compiler when compiling way
3036 <literal>mp</literal>. The variable
3037 <constant>WAY_CC_OPTS</constant> holds
3038 options to pass to the C compiler when compiling the
3039 standard way. (<Xref LinkEnd="sec-ways"> dicusses
3040 multi-way compilation.)</para>
3045 <term><constant><module>_CC_OPTS</constant>:</term>
3047 <para>options to pass to the C compiler that are specific
3048 to module <literal><module></literal>. For example,
3049 <constant>SMap_CC_OPTS</constant> gives the
3050 specific options to pass to the C compiler when compiling
3051 <filename>SMap.c</filename>.</para>
3056 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
3058 <para>extra options to pass to all C compilations. This
3059 is intended for command line use, thus:</para>
3062 gmake libHS.a EXTRA_CC_OPTS="-v"
3069 <sect2 id="sec-targets">
3070 <title>The main <filename>mk/target.mk</filename> file</title>
3071 <indexterm><primary>target.mk</primary></indexterm>
3073 <para><filename>target.mk</filename> contains canned rules for
3074 all the standard targets described in <Xref
3075 LinkEnd="sec-standard-targets">. It is complicated by the fact
3076 that you don't want all of these rules to be active in every
3077 <filename>Makefile</filename>. Rather than have a plethora of
3078 tiny files which you can include selectively, there is a single
3079 file, <filename>target.mk</filename>, which selectively includes
3080 rules based on whether you have defined certain variables in
3081 your <filename>Makefile</filename>. This section explains what
3082 rules you get, what variables control them, and what the rules
3083 do. Hopefully, you will also get enough of an idea of what is
3084 supposed to happen that you can read and understand any weird
3085 special cases yourself.</para>
3089 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
3091 <para>If <constant>HS_PROG</constant> is defined,
3092 you get rules with the following targets:</para>
3096 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
3098 <para>itself. This rule links
3099 <constant>$(OBJS)</constant> with the Haskell
3100 runtime system to get an executable called
3101 <constant>$(HS_PROG)</constant>.</para>
3106 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3109 <constant>$(HS_PROG)</constant> in
3110 <constant>$(bindir)</constant>.</para>
3119 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
3121 <para>is similar to <constant>HS_PROG</constant>,
3122 except that the link step links
3123 <constant>$(C_OBJS)</constant> with the C
3124 runtime system.</para>
3129 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3131 <para>is similar to <constant>HS_PROG</constant>,
3132 except that it links
3133 <constant>$(LIB_OBJS)</constant> to make the
3134 library archive <constant>$(LIBRARY)</constant>,
3135 and <literal>install</literal> installs it in
3136 <constant>$(libdir)</constant>.</para>
3141 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
3143 <para>…</para>
3148 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
3150 <para>…</para>
3155 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
3157 <para>If <constant>HS_SRCS</constant> is defined
3158 and non-empty, a rule for the target
3159 <literal>depend</literal> is included, which generates
3160 dependency information for Haskell programs. Similarly
3161 for <constant>C_SRCS</constant>.</para>
3166 <para>All of these rules are “double-colon” rules,
3170 install :: $(HS_PROG)
3171 ...how to install it...
3174 <para>GNU <command>make</command> treats double-colon rules as
3175 separate entities. If there are several double-colon rules for
3176 the same target it takes each in turn and fires it if its
3177 dependencies say to do so. This means that you can, for
3178 example, define both <constant>HS_PROG</constant> and
3179 <constant>LIBRARY</constant>, which will generate two rules for
3180 <literal>install</literal>. When you type <command>gmake
3181 install</command> both rules will be fired, and both the program
3182 and the library will be installed, just as you wanted.</para>
3185 <sect2 id="sec-subdirs">
3186 <title>Recursion</title>
3187 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3188 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3190 <para>In leaf <filename>Makefile</filename>s the variable
3191 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3192 is undefined. In non-leaf <filename>Makefile</filename>s,
3193 <constant>SUBDIRS</constant> is set to the list of
3194 sub-directories that contain subordinate
3195 <filename>Makefile</filename>s. <emphasis>It is up to you to
3196 set <constant>SUBDIRS</constant> in the
3197 <filename>Makefile</filename>.</emphasis> There is no automation
3198 here—<constant>SUBDIRS</constant> is too important to
3201 <para>When <constant>SUBDIRS</constant> is defined,
3202 <filename>target.mk</filename> includes a rather neat rule for
3203 the standard targets (<Xref LinkEnd="sec-standard-targets"> that
3204 simply invokes <command>make</command> recursively in each of
3205 the sub-directories.</para>
3207 <para><emphasis>These recursive invocations are guaranteed to
3208 occur in the order in which the list of directories is specified
3209 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3210 be important. For example, when you say <command>gmake
3211 boot</command> it can be important that the recursive invocation
3212 of <command>make boot</command> is done in one sub-directory
3213 (the include files, say) before another (the source files).
3214 Generally, put the most independent sub-directory first, and the
3215 most dependent last.</para>
3218 <sect2 id="sec-ways">
3219 <title>Way management</title>
3220 <indexterm><primary>way management</primary></indexterm>
3222 <para>We sometimes want to build essentially the same system in
3223 several different “ways”. For example, we want to build GHC's
3224 <literal>Prelude</literal> libraries with and without profiling,
3225 so that there is an appropriately-built library archive to link
3226 with when the user compiles his program. It would be possible
3227 to have a completely separate build tree for each such “way”,
3228 but it would be horribly bureaucratic, especially since often
3229 only parts of the build tree need to be constructed in multiple
3233 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3234 contains some clever magic to allow you to build several
3235 versions of a system; and to control locally how many versions
3236 are built and how they differ. This section explains the
3239 <para>The files for a particular way are distinguished by
3240 munging the suffix. The <quote>normal way</quote> is always
3241 built, and its files have the standard suffices
3242 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3243 In addition, you can build one or more extra ways, each
3244 distinguished by a <emphasis>way tag</emphasis>. The object
3245 files and interface files for one of these extra ways are
3246 distinguished by their suffix. For example, way
3247 <literal>mp</literal> has files
3248 <filename>.mp_o</filename> and
3249 <filename>.mp_hi</filename>. Library archives have their
3250 way tag the other side of the dot, for boring reasons; thus,
3251 <filename>libHS_mp.a</filename>.</para>
3253 <para>A <command>make</command> variable called
3254 <constant>way</constant> holds the current way tag.
3255 <emphasis><constant>way</constant> is only ever set on the
3256 command line of <command>gmake</command></emphasis> (usually in
3257 a recursive invocation of <command>gmake</command> by the
3258 system). It is never set inside a
3259 <filename>Makefile</filename>. So it is a global constant for
3260 any one invocation of <command>gmake</command>. Two other
3261 <command>make</command> variables,
3262 <constant>way_</constant> and
3263 <constant>_way</constant> are immediately derived from
3264 <constant>$(way)</constant> and never altered. If
3265 <constant>way</constant> is not set, then neither are
3266 <constant>way_</constant> and
3267 <constant>_way</constant>, and the invocation of
3268 <command>make</command> will build the <quote>normal
3269 way</quote>. If <constant>way</constant> is set, then the other
3270 two variables are set in sympathy. For example, if
3271 <constant>$(way)</constant> is “<literal>mp</literal>”,
3272 then <constant>way_</constant> is set to
3273 “<literal>mp_</literal>” and
3274 <constant>_way</constant> is set to
3275 “<literal>_mp</literal>”. These three variables are
3276 then used when constructing file names.</para>
3278 <para>So how does <command>make</command> ever get recursively
3279 invoked with <constant>way</constant> set? There are two ways
3280 in which this happens:</para>
3284 <para>For some (but not all) of the standard targets, when
3285 in a leaf sub-directory, <command>make</command> is
3286 recursively invoked for each way tag in
3287 <constant>$(WAYS)</constant>. You set
3288 <constant>WAYS</constant> in the
3289 <filename>Makefile</filename> to the list of way tags you
3290 want these targets built for. The mechanism here is very
3291 much like the recursive invocation of
3292 <command>make</command> in sub-directories (<Xref
3293 LinkEnd="sec-subdirs">). It is up to you to set
3294 <constant>WAYS</constant> in your
3295 <filename>Makefile</filename>; this is how you control what
3296 ways will get built.</para>
3300 <para>For a useful collection of targets (such as
3301 <filename>libHS_mp.a</filename>,
3302 <filename>Foo.mp_o</filename>) there is a rule which
3303 recursively invokes <command>make</command> to make the
3304 specified target, setting the <constant>way</constant>
3305 variable. So if you say <command>gmake
3306 Foo.mp_o</command> you should see a recursive
3307 invocation <command>gmake Foo.mp_o way=mp</command>,
3308 and <emphasis>in this recursive invocation the pattern rule
3309 for compiling a Haskell file into a <filename>.o</filename>
3310 file will match</emphasis>. The key pattern rules (in
3311 <filename>suffix.mk</filename>) look like this:
3315 $(HC) $(HC_OPTS) $< -o $@
3322 <para>You can invoke <command>make</command> with a
3323 particular <literal>way</literal> setting yourself, in order
3324 to build files related to a particular
3325 <literal>way</literal> in the current directory. eg.
3331 will build files for the profiling way only in the current
3338 <title>When the canned rule isn't right</title>
3340 <para>Sometimes the canned rule just doesn't do the right thing.
3341 For example, in the <literal>nofib</literal> suite we want the
3342 link step to print out timing information. The thing to do here
3343 is <emphasis>not</emphasis> to define
3344 <constant>HS_PROG</constant> or
3345 <constant>C_PROG</constant>, and instead define a special
3346 purpose rule in your own <filename>Makefile</filename>. By
3347 using different variable names you will avoid the canned rules
3348 being included, and conflicting with yours.</para>
3352 <sect1 id="building-docs">
3353 <title>Building the documentation</title>
3355 <sect2 id="pre-supposed-doc-tools">
3356 <title>Tools for building the Documentation</title>
3358 <para>The following additional tools are required if you want to
3359 format the documentation that comes with the
3360 <literal>fptools</literal> projects:</para>
3364 <term>DocBook</term>
3365 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3366 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3368 <para>Much of our documentation is written in SGML, using
3369 the DocBook DTD. Instructions on installing and
3370 configuring the DocBook tools are below.</para>
3376 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3377 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3379 <para>A decent TeX distribution is required if you want to
3380 produce printable documentation. We recomment teTeX,
3381 which includes just about everything you need.</para>
3386 <term>Haddock</term>
3387 <indexterm><primary>Haddock</primary>
3390 <para>Haddock is a Haskell documentation tool that we use
3391 for automatically generating documentation from the
3392 library source code. It is an <literal>fptools</literal>
3393 project in itself. To build documentation for the
3394 libraries (<literal>fptools/libraries</literal>) you
3395 should check out and build Haddock in
3396 <literal>fptools/haddock</literal>. Haddock requires GHC
3404 <title>Installing the DocBook tools</title>
3407 <title>Installing the DocBook tools on Linux</title>
3409 <para>If you're on a recent RedHat system (7.0+), you probably
3410 have working DocBook tools already installed. The configure
3411 script should detect your setup and you're away.</para>
3413 <para>If you don't have DocBook tools installed, and you are
3414 using a system that can handle RedHat RPM packages, you can
3415 probably use the <ULink
3416 URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3417 DocBook tools</ULink>, which is the most shrink-wrapped SGML
3418 suite that we could find. You need all the RPMs except for
3419 psgml (i.e. <Filename>docbook</Filename>,
3420 <Filename>jade</Filename>, <Filename>jadetex</Filename>,
3421 <Filename>sgmlcommon</Filename> and
3422 <Filename>stylesheets</Filename>). Note that most of these
3423 RPMs are architecture neutral, so are likely to be found in a
3424 <Filename>noarch</Filename> directory. The SuSE RPMs also
3425 work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
3426 (7.0 and later should be OK), but they are easy to fix: just
3428 <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
3429 to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
3433 <title>Installing DocBook on FreeBSD</title>
3435 <para>On FreeBSD systems, the easiest way to get DocBook up
3436 and running is to install it from the ports tree or a
3437 pre-compiled package (packages are available from your local
3438 FreeBSD mirror site).</para>
3440 <para>To use the ports tree, do this:
3442 $ cd /usr/ports/textproc/docproj
3445 This installs the FreeBSD documentation project tools, which
3446 includes everything needed to format the GHC
3447 documentation.</para>
3451 <title>Installing from binaries on Windows</title>
3453 <Para>It's a good idea to use Norman Walsh's <ULink
3454 URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3455 notes</ULink> as a guide. You should get version 3.1 of
3456 DocBook, and note that his file <Filename>test.sgm</Filename>
3457 won't work, as it needs version 3.0. You should unpack Jade
3458 into <Filename>\Jade</Filename>, along with the entities,
3459 DocBook into <Filename>\docbook</Filename>, and the DocBook
3460 stylesheets into <Filename>\docbook\stylesheets</Filename> (so
3461 they actually end up in
3462 <Filename>\docbook\stylesheets\docbook</Filename>).</para>
3467 <title>Installing the DocBook tools from source</title>
3472 <para>Install <ULink
3473 URL="http://openjade.sourceforge.net/">OpenJade</ULink>
3474 (Windows binaries are available as well as sources). If you
3475 want DVI, PS, or PDF then install JadeTeX from the
3476 <Filename>dsssl</Filename> subdirectory. (If you get the
3480 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
3483 your version of <Command>hyperref</Command> is out of date;
3484 download it from CTAN
3485 (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
3486 and make it, ensuring that you have first removed or renamed
3487 your old copy. If you start getting file not found errors
3488 when making the test for <Command>hyperref</Command>, you
3489 can abort at that point and proceed straight to
3490 <Command>make install</Command>, or enter them as
3491 <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
3493 <para>Make links from <Filename>virtex</Filename> to
3494 <Filename>jadetex</Filename> and
3495 <Filename>pdfvirtex</Filename> to
3496 <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
3497 and PDF output will not work). Copy
3498 <Filename>dsssl/*.{dtd,dsl}</Filename> and
3499 <Filename>catalog</Filename> to
3500 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3504 <title>DocBook and the DocBook stylesheets</title>
3506 <para>Get a Zip of <ULink
3507 URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
3508 and install the contents in
3509 <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
3511 <para>Get the <ULink
3512 URL="http://nwalsh.com/docbook/dsssl/">DocBook
3513 stylesheets</ULink> and install in
3514 <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
3515 (thereby creating a subdirectory docbook). For indexing,
3516 copy or link <Filename>collateindex.pl</Filename> from the
3517 DocBook stylesheets archive in <Filename>bin</Filename> into
3518 a directory on your <Constant>PATH</Constant>.</para>
3520 <para>Download the <ULink
3521 URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3522 entities</ULink> into
3523 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3529 <title>Configuring the DocBook tools</title>
3531 <Para>Once the DocBook tools are installed, the configure script
3532 will detect them and set up the build system accordingly. If you
3533 have a system that isn't supported, let us know, and we'll try
3538 <title>Remaining problems</title>
3540 <para>If you install from source, you'll get a pile of warnings
3543 <Screen>DTDDECL catalog entries are not supported</Screen>
3545 every time you build anything. These can safely be ignored, but
3546 if you find them tedious you can get rid of them by removing all
3547 the <Constant>DTDDECL</Constant> entries from
3548 <Filename>docbook.cat</Filename>.</para>
3552 <title>Building the documentation</title>
3554 <para>To build documentation in a certain format, you can
3555 say, for example,</para>
3561 <para>to build HTML documentation below the current directory.
3562 The available formats are: <literal>dvi</literal>,
3563 <literal>ps</literal>, <literal>pdf</literal>,
3564 <literal>html</literal>, and <literal>rtf</literal>. Note that
3565 not all documentation can be built in all of these formats: HTML
3566 documentation is generally supported everywhere, and DocBook
3567 documentation might support the other formats (depending on what
3568 other tools you have installed).</para>
3570 <para>All of these targets are recursive; that is, saying
3571 <literal>make html</literal> will make HTML docs for all the
3572 documents recursively below the current directory.</para>
3574 <para>Because there are many different formats that the DocBook
3575 documentation can be generated in, you have to select which ones
3576 you want by setting the <literal>SGMLDocWays</literal> variable
3577 to a list of them. For example, in
3578 <filename>build.mk</filename> you might have a line:</para>
3581 SGMLDocWays = html ps
3584 <para>This will cause the documentation to be built in the requested
3585 formats as part of the main build (the default is not to build
3586 any documentation at all).</para>
3590 <title>Installing the documentation</title>
3592 <para>To install the documentation, use:</para>
3598 <para>This will install the documentation into
3599 <literal>$(datadir)</literal> (which defaults to
3600 <literal>$(prefix)/share</literal>). The exception is HTML
3601 documentation, which goes into
3602 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3604 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3605 to a list of formats, the <literal>install-docs</literal> target
3606 won't do anything for SGML documentation.</para>
3612 <sect1 id="sec-porting-ghc">
3613 <title>Porting GHC</title>
3615 <para>This section describes how to port GHC to a currenly
3616 unsupported platform. There are two distinct
3617 possibilities:</para>
3621 <para>The hardware architecture for your system is already
3622 supported by GHC, but you're running an OS that isn't
3623 supported (or perhaps has been supported in the past, but
3624 currently isn't). This is the easiest type of porting job,
3625 but it still requires some careful bootstrapping. Proceed to
3626 <xref linkend="sec-booting-from-hc">.</para>
3630 <para>Your system's hardware architecture isn't supported by
3631 GHC. This will be a more difficult port (though by comparison
3632 perhaps not as difficult as porting gcc). Proceed to <xref
3633 linkend="unregisterised-porting">.</para>
3637 <sect2 id="sec-booting-from-hc">
3638 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3640 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3641 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3642 <indexterm><primary>porting GHC</primary></indexterm>
3644 <para>Bootstrapping GHC on a system without GHC already
3645 installed is achieved by taking the intermediate C files (known
3646 as HC files) from a GHC compilation on a supported system to the
3647 target machine, and compiling them using gcc to get a working
3650 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3651 from C. We recommend using GHC 6.0.1 or
3652 later.</emphasis></para>
3654 <para>HC files are platform-dependent, so you have to get a set
3655 that were generated on similar hardware. There may be some
3656 supplied on the GHC download page, otherwise you'll have to
3657 compile some up yourself, or start from
3658 <emphasis>unregisterised</emphasis> HC files - see <xref
3659 linkend="unregisterised-porting">.</para>
3661 <para>The following steps should result in a working GHC build
3662 with full libraries:</para>
3666 <para>Unpack the HC files on top of a fresh source tree
3667 (make sure the source tree version matches the version of
3668 the HC files <emphasis>exactly</emphasis>!). This will
3669 place matching <filename>.hc</filename> files next to the
3670 corresponding Haskell source (<filename>.hs</filename> or
3671 <filename>.lhs</filename>) in the compiler subdirectory
3672 <filename>ghc/compiler</filename> and in the libraries
3673 (subdirectories of <filename>hslibs</filename> and
3674 <literal>libraries</literal>).</para>
3678 <para>The actual build process is fully automated by the
3679 <filename>hc-build</filename> script located in the
3680 <filename>distrib</filename> directory. If you eventually
3681 want to install GHC into the directory
3682 <replaceable>dir</replaceable>, the following
3683 command will execute the whole build process (it won't
3684 install yet):</para>
3687 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3689 <indexterm><primary>--hc-build</primary></indexterm>
3691 <para>By default, the installation directory is
3692 <filename>/usr/local</filename>. If that is what you want,
3693 you may omit the argument to <filename>hc-build</filename>.
3694 Generally, any option given to <filename>hc-build</filename>
3695 is passed through to the configuration script
3696 <filename>configure</filename>. If
3697 <filename>hc-build</filename> successfully completes the
3698 build process, you can install the resulting system, as
3708 <sect2 id="unregisterised-porting">
3709 <title>Porting GHC to a new architecture</title>
3711 <para>The first step in porting to a new architecture is to get
3712 an <firstterm>unregisterised</firstterm> build working. An
3713 unregisterised build is one that compiles via vanilla C only.
3714 By contrast, a registerised build uses the following
3715 architecture-specific hacks for speed:</para>
3719 <para>Global register variables: certain abstract machine
3720 <quote>registers</quote> are mapped to real machine
3721 registers, depending on how many machine registers are
3723 <filename>ghc/includes/MachRegs.h</filename>).</para>
3727 <para>Assembly-mangling: when compiling via C, we feed the
3728 assembly generated by gcc though a Perl script known as the
3729 <firstterm>mangler</firstterm> (see
3730 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3731 mangler rearranges the assembly to support tail-calls and
3732 various other optimisations.</para>
3736 <para>In an unregisterised build, neither of these hacks are
3737 used — the idea is that the C code generated by the
3738 compiler should compile using gcc only. The lack of these
3739 optimisations costs about a factor of two in performance, but
3740 since unregisterised compilation is usually just a step on the
3741 way to a full registerised port, we don't mind too much.</para>
3743 <para>Notes on GHC portability in general: we've tried to stick
3744 to writing portable code in most parts of the system, so it
3745 should compile on any POSIXish system with gcc, but in our
3746 experience most systems differ from the standards in one way or
3747 another. Deal with any problems as they arise - if you get
3748 stuck, ask the experts on
3749 <email>glasgow-haskell-users@haskell.org</email>.</para>
3751 <para>Lots of useful information about the innards of GHC is
3752 available in the <ulink
3753 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3754 Commentary</ulink>, which might be helpful if you run into some
3755 code which needs tweaking for your system.</para>
3758 <title>Cross-compiling to produce an unregisterised GHC</title>
3760 <para>In this section, we explain how to bootstrap GHC on a
3761 new platform, using unregisterised intermediate C files. We
3762 haven't put a great deal of effort into automating this
3763 process, for two reasons: it is done very rarely, and the
3764 process usually requires human intervention to cope with minor
3765 porting issues anyway.</para>
3767 <para>The following step-by-step instructions should result in
3768 a fully working, albeit unregisterised, GHC. Firstly, you
3769 need a machine that already has a working GHC (we'll call this
3770 the <firstterm>host</firstterm> machine), in order to
3771 cross-compile the intermediate C files that we will use to
3772 bootstrap the compiler on the <firstterm>target</firstterm>
3777 <para>On the target machine:</para>
3781 <para>Unpack a source tree (preferably a released
3782 version). We will call the path to the root of this
3783 tree <replaceable>T</replaceable>.</para>
3788 $ cd <replaceable>T</replaceable>
3789 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
3792 <para>You might need to update
3793 <filename>configure.in</filename> to recognise the new
3794 architecture, and re-generate
3795 <filename>configure</filename> with
3796 <literal>autoreconf</literal>.</para>
3801 $ cd <replaceable>T</replaceable>/ghc/includes
3809 <para>On the host machine:</para>
3813 <para>Unpack a source tree (same released version). Call
3814 this directory <replaceable>H</replaceable>.</para>
3819 $ cd <replaceable>H</replaceable>
3826 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3827 with the following contents:</para>
3830 GhcUnregisterised = YES
3831 GhcLibHcOpts = -O -H32m -keep-hc-files
3834 GhcWithNativeCodeGen = NO
3835 GhcWithInterpreter = NO
3836 GhcStage1HcOpts = -O -H32m -fasm
3837 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3843 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3846 <para>change <literal>TARGETPLATFORM</literal>
3847 appropriately, and set the variables involving
3848 <literal>TARGET</literal> to the correct values for
3849 the target platform. This step is necessary because
3850 currently <literal>configure</literal> doesn't cope
3851 with specifying different values for the
3852 <literal>--host</literal> and
3853 <literal>--target</literal> flags.</para>
3856 <para>copy <literal>LeadingUnderscore</literal>
3857 setting from target.</para>
3864 <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
3866 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3867 Note that we are building on the host machine, using the
3868 target machine's <literal>config.h</literal> file. This
3869 is so that the intermediate C files generated here will
3870 be suitable for compiling on the target system.</para>
3875 <para>Touch <literal>config.h</literal>, just to make
3876 sure it doesn't get replaced during the build:</para>
3878 $ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
3882 <para>Now build the compiler:</para>
3884 $ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
3885 $ cd <replaceable>H</replaceable>/ghc && make boot && make
3887 <para>Don't worry if the build falls over in the RTS, we
3888 don't need the RTS yet.</para>
3893 $ cd <replaceable>H</replaceable>/libraries
3894 $& make boot && make
3900 $ cd <replaceable>H</replaceable>/ghc
3901 $ make boot stage=2 && make stage=2
3907 $ cd <replaceable>H</replaceable>/ghc/utils
3909 $ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
3910 EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3916 $ cd <replaceable>H</replaceable>
3917 $ make hc-file-bundle Project=Ghc
3923 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3924 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3930 <para>On the target machine:</para>
3932 <para>At this stage we simply need to bootstrap a compiler
3933 from the intermediate C files we generated above. The
3934 process of bootstrapping from C files is automated by the
3935 script in <literal>distrib/hc-build</literal>, and is
3936 described in <xref linkend="sec-booting-from-hc">.</para>
3939 $ ./distrib/hc-build --enable-hc-boot-unregisterised
3942 <para>However, since this is a bootstrap on a new machine,
3943 the automated process might not run to completion the
3944 first time. For that reason, you might want to treat the
3945 <literal>hc-build</literal> script as a list of
3946 instructions to follow, rather than as a fully automated
3947 script. This way you'll be able to restart the process
3948 part-way through if you need to fix anything on the
3951 <para>Don't bother with running
3952 <literal>make install</literal> in the newly
3953 bootstrapped tree; just use the compiler in that tree to
3954 build a fresh compiler from scratch, this time without
3955 booting from C files. Before doing this, you might want
3956 to check that the bootstrapped compiler is generating
3957 working binaries:</para>
3961 main = putStrLn "Hello World!\n"
3963 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3968 <para>Once you have the unregisterised compiler up and
3969 running, you can use it to start a registerised port. The
3970 following sections describe the various parts of the
3971 system that will need architecture-specific tweaks in
3972 order to get a registerised build going.</para>
3979 <title>Porting the RTS</title>
3981 <para>The following files need architecture-specific code for a
3982 registerised build:</para>
3986 <term><filename>ghc/includes/MachRegs.h</filename></term>
3987 <indexterm><primary><filename>MachRegs.h</filename></primary>
3990 <para>Defines the STG-register to machine-register
3991 mapping. You need to know your platform's C calling
3992 convention, and which registers are generally available
3993 for mapping to global register variables. There are
3994 plenty of useful comments in this file.</para>
3998 <term><filename>ghc/includes/TailCalls.h</filename></term>
3999 <indexterm><primary><filename>TailCalls.h</filename></primary>
4002 <para>Macros that cooperate with the mangler (see <xref
4003 linkend="sec-mangler">) to make proper tail-calls
4008 <term><filename>ghc/rts/Adjustor.c</filename></term>
4009 <indexterm><primary><filename>Adjustor.c</filename></primary>
4013 <literal>foreign import "wrapper"</literal>
4015 <literal>foreign export dynamic</literal>).
4016 Not essential for getting GHC bootstrapped, so this file
4017 can be deferred until later if necessary.</para>
4021 <term><filename>ghc/rts/StgCRun.c</filename></term>
4022 <indexterm><primary><filename>StgCRun.c</filename></primary>
4025 <para>The little assembly layer between the C world and
4026 the Haskell world. See the comments and code for the
4027 other architectures in this file for pointers.</para>
4031 <term><filename>ghc/rts/MBlock.h</filename></term>
4032 <term><filename>ghc/rts/MBlock.c</filename></term>
4033 <indexterm><primary><filename>MBlock.h</filename></primary>
4035 <indexterm><primary><filename>MBlock.c</filename></primary>
4038 <para>These files are really OS-specific rather than
4039 architecture-specific. In <filename>MBlock.h</filename>
4040 is specified the absolute location at which the RTS
4041 should try to allocate memory on your platform (try to
4042 find an area which doesn't conflict with code or dynamic
4043 libraries). In <filename>Mblock.c</filename> you might
4044 need to tweak the call to <literal>mmap()</literal> for
4051 <sect3 id="sec-mangler">
4052 <title>The mangler</title>
4054 <para>The mangler is an evil Perl-script that rearranges the
4055 assembly code output from gcc to do two main things:</para>
4059 <para>Remove function prologues and epilogues, and all
4060 movement of the C stack pointer. This is to support
4061 tail-calls: every code block in Haskell code ends in an
4062 explicit jump, so we don't want the C-stack overflowing
4063 while we're jumping around between code blocks.</para>
4066 <para>Move the <firstterm>info table</firstterm> for a
4067 closure next to the entry code for that closure. In
4068 unregisterised code, info tables contain a pointer to the
4069 entry code, but in registerised compilation we arrange
4070 that the info table is shoved right up against the entry
4071 code, and addressed backwards from the entry code pointer
4072 (this saves a word in the info table and an extra
4073 indirection when jumping to the closure entry
4078 <para>The mangler is abstracted to a certain extent over some
4079 architecture-specific things such as the particular assembler
4080 directives used to herald symbols. Take a look at the
4081 definitions for other architectures and use these as a
4082 starting point.</para>
4086 <title>The native code generator</title>
4088 <para>The native code generator isn't essential to getting a
4089 registerised build going, but it's a desirable thing to have
4090 because it can cut compilation times in half. The native code
4091 generator is described in some detail in the <ulink
4092 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
4093 commentary</ulink>.</para>
4099 <para>To support GHCi, you need to port the dynamic linker
4100 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
4101 currently supports the ELF and PEi386 object file formats - if
4102 your platform uses one of these then things will be
4103 significantly easier. The majority of Unix platforms use the
4104 ELF format these days. Even so, there are some
4105 machine-specific parts of the ELF linker: for example, the
4106 code for resolving particular relocation types is
4107 machine-specific, so some porting of this code to your
4108 architecture will probaly be necessary.</para>
4110 <para>If your system uses a different object file format, then
4111 you have to write a linker — good luck!</para>
4117 <sect1 id="sec-build-pitfalls">
4118 <title>Known pitfalls in building Glasgow Haskell
4120 <indexterm><primary>problems, building</primary></indexterm>
4121 <indexterm><primary>pitfalls, in building</primary></indexterm>
4122 <indexterm><primary>building pitfalls</primary></indexterm></title>
4125 WARNINGS about pitfalls and known “problems”:
4134 One difficulty that comes up from time to time is running out of space
4135 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
4136 compensate for the vagaries of different sysadmin approaches to temp
4138 <indexterm><primary>tmp, running out of space in</primary></indexterm>
4140 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
4141 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
4144 The best way around it is to say
4147 export TMPDIR=<dir>
4150 in your <filename>build.mk</filename> file.
4151 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
4160 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
4161 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
4169 When compiling via C, you'll sometimes get “warning: assignment from
4170 incompatible pointer type” out of GCC. Harmless.
4177 Similarly, <command>ar</command>chiving warning messages like the following are not
4181 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
4182 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
4192 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
4193 get an “Out of heap space” error message. These can vary with the
4194 vagaries of different systems, it seems. The solution is simple:
4201 If you're compiling with GHC 4.00 or later, then the
4202 <emphasis>maximum</emphasis> heap size must have been reached. This
4203 is somewhat unlikely, since the maximum is set to 64M by default.
4204 Anyway, you can raise it with the
4205 <option>-optCrts-M<size></option> flag (add this flag to
4206 <constant><module>_HC_OPTS</constant>
4207 <command>make</command> variable in the appropriate
4208 <filename>Makefile</filename>).
4215 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
4224 and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
4225 <constant><module>_HC_OPTS</constant>.)
4227 Alternatively, just cut to the chase:
4231 % make EXTRA_HC_OPTS=-optCrts-M128M
4240 If you try to compile some Haskell, and you get errors from GCC about
4241 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
4242 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
4244 As <command>fixincludes</command> is now automagically run as part of GCC installation,
4245 this bug also suggests that you have an old GCC.
4253 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
4257 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
4258 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
4260 ? # or, on some machines: ar s $i
4265 We'd be interested to know if this is still necessary.
4273 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
4274 a bit from one Unix to another. One particular gotcha is macro calls
4279 SLIT("Hello, world")
4283 Some <command>cpp</command>s treat the comma inside the string as separating two macro
4284 arguments, so you get
4288 :731: macro `SLIT' used with too many (2) args
4292 Alas, <command>cpp</command> doesn't tell you the offending file!
4294 Workaround: don't put weird things in string args to <command>cpp</command> macros.
4305 <Sect1 id="platforms"><Title>Platforms, scripts, and file names</Title>
4307 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
4308 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
4311 <sect2 id="cygwin-and-mingw"><Title>Windows platforms: Cygwin, MSYS, and MinGW</Title>
4313 <para> The build system is built around Unix-y makefiles. Because it's not native,
4314 the Windows situation for building GHC is particularly confusing. This section
4315 tries to clarify, and to establish terminology.</para>
4317 <sect3 id="ghc-mingw"><title>MinGW</title>
4319 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
4320 is a collection of header
4321 files and import libraries that allow one to use <command>gcc</command> and produce
4322 native Win32 programs that do not rely on any third-party DLLs. The
4323 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
4324 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
4328 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
4333 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
4335 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
4336 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
4337 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
4338 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
4339 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
4343 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
4344 compile code that has access to all of Posix. The price is that the executables must be
4345 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
4346 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4347 does not change, but the implementation certainly does. Even the interfaces to functions
4348 it exports seem to change occasionally. </para>
4352 MSYS is a fork of the Cygwin tree, so they
4353 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
4354 through fewer layers, so MSYS is quite a bit faster too.
4357 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
4358 compile binaries that run with no DLL support, on any Win32 system.
4359 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
4360 <command>cvs</command>, <command>ssh</command> etc. To get these, you have to download the
4361 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
4363 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
4364 <command>ssh</command> and so on),
4365 not by programs compiled under MSYS.
4373 <sect3><title>Targeting MinGW</title>
4375 <para>We want GHC to compile programs that work on any Win32 system. Hence:
4378 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
4379 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
4380 will work on any system, but it also means that the programs GHC compiles do not have access
4381 to all of Posix. In particular, they cannot import the (Haskell) Posix
4382 library; they have to do
4383 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
4384 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
4388 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
4389 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
4392 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
4393 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
4394 that targets Cygwin instead. The up-side of GHC-cygwin is
4395 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4396 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
4399 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
4400 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
4401 GHC; both work fine, though MSYS is rather lighter weight.</para>
4403 <para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>. It
4404 uses the <Command>gcc</Command> that you specify using the
4405 <option>--with-gcc</option> flag when you run
4406 <Command>configure</Command> (see below).
4407 The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
4408 to compile any C files, so that it will in turn invoke the correct <Command>gcc</Command> rather that
4409 whatever one happens to be in your path. However, the makefiles do use whatever <Command>ld</Command>
4410 and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
4411 used to glom together .o files into a bigger .o file, or a .a file,
4412 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
4413 Cygwin and MinGW use the same .o file format. So its ok.
4417 <sect3><title> File names </title>
4419 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
4423 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
4424 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
4426 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
4427 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
4428 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
4433 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
4437 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
4439 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
4445 <sect3><title>HOST_OS vs TARGET_OS</title>
4448 In the source code you'll find various ifdefs looking like:
4450 #ifdef mingw32_HOST_OS
4456 #ifdef mingw32_TARGET_OS
4460 These macros are set by the configure script (via the file config.h).
4461 Which is which? The criterion is this. In the ifdefs in GHC's source code:
4464 The "host" system is the one on which GHC itself will be run.
4467 The "target" system is the one for which the program compiled by GHC will be run.
4470 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
4471 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
4478 <sect2><title>Wrapper scripts</title>
4481 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
4482 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
4483 GHC itself as an example:
4486 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
4487 paths to the front of the source file <filename>ghc.sh</filename>,
4488 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
4489 where to find its supporting files.
4493 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
4494 native Windows shell <command>cmd</command> (e.g. limits on the length
4495 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
4496 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
4497 and from that figures out where the supporting files are.
4500 (You can find the layout of GHC's supporting files in the
4501 section "Layout of installed files" of Section 2 of the GHC user guide.)
4504 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
4505 execute a program that has just been built in a build tree. The difference is that the
4506 layout of the supporting files is different.
4507 In this case, whether on Windows or Unix, we always use a shell script. This works OK
4508 on Windows because the script is executed by MSYS or Cygwin, which don't have the
4509 shortcomings of the native Windows <command>cmd</command> shell.
4516 <Sect1 id="winbuild"><Title>Instructions for building under Windows</Title>
4519 This section gives detailed instructions for how to build
4520 GHC from source on your Windows machine. Similar instructions for
4521 installing and running GHC may be found in the user guide. In general,
4522 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
4525 Make sure you read the preceding section on platforms (<xref linkend="platforms">)
4526 before reading section.
4530 <Sect2><Title>Installing and configuring MSYS</Title>
4533 MSYS is a lightweight alternative to Cygwin.
4534 You don't need MSYS to <emphasis>use</emphasis> GHC,
4535 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
4536 Here's how to install MSYS.
4539 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
4540 download the following (of course, the version numbers will differ):
4542 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
4544 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
4545 This provides <command>make</command>, <command>autoconf</command>,
4546 <command>ssh</command>, <command>cvs</command> and probably more besides.
4549 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
4553 Set the following environment variables
4555 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path. (Of course, the version number may differ.)
4558 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
4559 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
4562 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
4565 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
4569 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
4576 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
4577 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
4578 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
4579 file has too-liberal permissinos.
4586 <Sect2><Title>Installing and configuring Cygwin</Title>
4588 <para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
4589 but you do need it or MSYS to <emphasis>build</emphasis> GHC.</para>
4591 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4592 The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
4593 During the installation dialogue, make sure that you select all of the following:
4596 <command>cvs</command>,
4599 <command>openssh</command>,
4602 <command>autoconf</command>,
4605 <command>binutils</command> (includes ld and (I think) ar),
4608 <command>gcc</command>,
4611 <command>flex</command>,
4614 <command>make</command>.
4617 If you miss out any of these, strange things will happen to you. To see thse packages,
4618 click on the "View" button in the "Select Packages"
4619 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
4620 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
4622 <para> Now set the following user environment variables:
4625 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4626 <constant>PATH</constant></para></listitem>
4630 Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
4631 don't do this you get very weird messages when you type
4632 <Command>make</Command>, such as:
4634 /c: /c: No such file or directory
4639 <listitem><para> Set <constant>SHELL</constant> to
4640 <Filename>c:/cygwin/bin/bash</Filename>. When you invoke a shell in Emacs, this
4641 <constant>SHELL</constant> is what you get.
4644 <listitem><para> Set <constant>HOME</constant> to point to your
4645 home directory. This is where, for example,
4646 <command>bash</command> will look for your <filename>.bashrc</filename>
4647 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4653 There are a few other things to do:
4657 By default, cygwin provides the command shell <filename>ash</filename>
4658 as <filename>sh.exe</filename>. We have often seen build-system problems that
4659 turn out to be due to bugs in <filename>ash</filename>
4661 and length of command lines). On the other hand <filename>bash</filename> seems
4663 So, in <filename>cygwin/bin</filename>
4664 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
4665 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
4666 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
4667 you can't rename a running program!
4673 Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
4674 (and similarly for <Command>sh</Command>). Notice the hardwired path!
4675 So you need to ensure that your <Filename>/bin</Filename> directory has the following
4678 <listitem> <para><Command>sh</Command></para></listitem>
4679 <listitem> <para><Command>perl</Command></para></listitem>
4680 <listitem> <para><Command>cat</Command></para></listitem>
4682 All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
4683 installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
4684 <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
4685 (You can discover where your Cygwin
4686 root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
4687 Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
4688 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
4689 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
4695 <para>Finally, here are some things to be aware of when using Cygwin:
4697 <listitem> <para>Cygwin doesn't deal well with filenames that include
4698 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4702 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4703 magical text in it. So other programs that don't use Cygwin's
4704 I/O libraries won't recognise such files as symlinks.
4705 In particular, programs compiled by GHC are meant to be runnable
4706 without having Cygwin, so they don't use the Cygwin library, so
4707 they don't recognise symlinks.
4711 Win32 has a <command>find</command> command which is not the same as Cygwin's find.
4712 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4713 before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4714 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4715 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4723 <Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
4725 <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
4726 you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
4727 (not ssh) in the Cygwin list of applications!</para>
4729 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
4733 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
4734 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
4735 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
4736 and run it as follows:
4738 c:\tmp> set CYGWIN32=tty
4739 c:\tmp> c:/user/local/bin/ssh-keygen1
4744 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
4745 To determine your home directory <command>ssh</command> first looks in
4746 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
4747 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
4748 the setting of the environment variable $HOME</emphasis>. If the home directory is
4749 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
4751 ssh -v cvs.haskell.org
4753 which makes <command>ssh</command> print out information about its activity.
4755 <para> You can fix this problem, either by correcting the home-directory field in
4756 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
4757 you do that, <command>ssh</command> uses the $HOME environment variable instead.
4763 <para>To protect your
4764 <literal>.ssh</literal> from access by anyone else,
4765 right-click your <literal>.ssh</literal> directory, and
4766 select <literal>Properties</literal>. If you are not on
4767 the access control list, add yourself, and give yourself
4768 full permissions (the second panel). Remove everyone else
4769 from the access control list. Don't leave them there but
4770 deny them access, because 'they' may be a list that
4771 includes you!</para>
4775 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
4776 you to have Unix permissions 600 (read/write for owner only)
4777 on the <literal>.ssh/identity</literal> file, else it
4778 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
4779 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
4780 The solution seems to be to set the $CYGWIN environment
4781 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
4782 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
4783 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
4790 <Sect2><Title>Other things you need to install</Title>
4792 <para>You have to install the following other things to build GHC:
4796 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4797 This is what you will use to compile GHC. Add it in your
4798 <constant>PATH</constant>: the installer tells you the path element
4799 you need to add upon completion.
4805 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4806 Happy is a parser generator used to compile the Haskell grammar. Add it in your
4807 <constant>PATH</constant>.
4812 <para>Install Alex. This can be done by building from the
4813 source distribution in the usual way. Sources are
4814 available from <ulink
4815 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
4819 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4820 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">).
4821 Just pick up a mingw bundle at
4822 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4823 We install it in <filename>c:/mingw</filename>.
4825 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
4826 They are only going to get used by explicit access (via the --with-gcc flag you
4827 give to <Command>configure</Command> later). If you do add them to your path
4828 you are likely to get into a mess because their names overlap with Cygwin binaries.
4834 <para>We use <command>emacs</command> a lot, so we install that too.
4835 When you are in <filename>fptools/ghc/compiler</filename>, you can use
4836 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
4837 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
4838 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
4839 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
4840 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
4846 <para> Finally, check out a copy of GHC sources from
4847 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
4854 <Sect2><Title>Building GHC</Title>
4857 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
4858 the bullets below only tell
4859 you about Windows-specific wrinkles.</para>
4863 If you used <Command>autoconf</Command> instead of <Command>autoreconf</Command>,
4864 you'll get an error when you run <filename>./configure</filename>:
4867 creating mk/config.h
4868 mk/config.h is unchanged
4870 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4871 ./configure: ./configure: No such file or directory
4872 configure: error: ./configure failed for ghc
4877 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
4878 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
4881 /usr/bin/autoconf: cannot create configure: permission denied
4883 Solution: delete <filename>configure</filename> first.
4888 You either need to add <filename>ghc</filename> to your
4889 <constant>PATH</constant> before you invoke
4890 <Command>configure</Command>, or use the <Command>configure</Command>
4891 option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
4896 If you are paranoid, delete <filename>config.cache</filename> if it exists.
4897 This file occasionally remembers out-of-date configuration information, which
4898 can be really confusing.
4904 After <command>autoreconf</command> run <command>./configure</command> in
4905 <filename>fptools/</filename> thus:
4908 ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
4910 This is the point at which you specify that you are building GHC-mingw
4911 (see <xref linkend="ghc-mingw">). </para>
4913 <para> Both these options are important! It's possible to get into
4914 trouble using the wrong C compiler!</para>
4916 Furthermore, it's <emphasis>very important</emphasis> that you specify a
4917 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
4918 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
4919 understand a Cygwin path. For example, if you
4920 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
4921 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
4922 time it tries to invoke it. Worse, the failure comes with
4923 no error message whatsoever. GHC simply fails silently when first invoked,
4924 typically leaving you with this:
4926 make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
4927 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
4928 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
4929 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
4930 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
4931 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
4932 -optc-fomit-frame-pointer -O2 -static
4933 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
4934 make[2]: *** [Adjustor.o] Error 1
4935 make[1]: *** [all] Error 1
4936 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
4937 make: *** [all] Error 1
4943 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
4944 you'll have to do something more like:
4946 ./configure --with-gcc=...the Cygwin gcc...
4951 <listitem><para> You almost certainly want to set
4955 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
4956 This tells the build system not to split each library into a myriad of little object files, one
4957 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
4958 it dramatically increases the time taken to build the libraries in the first place.
4962 <listitem><para> Do not attempt to build the documentation.
4963 It needs all kinds of wierd Jade stuff that we haven't worked out for
4964 Win32.</para></listitem>
projects / ghc-hetmet.git / blob