1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
3 <Article id="building-guide">
7 <Title>Building the Glasgow Functional Programming Tools Suite</Title>
8 <Author><OtherName>The GHC Team</OtherName></Author>
9 <Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
10 <PubDate>November 2001</PubDate>
13 <para>The Glasgow fptools suite is a collection of Functional
14 Programming related tools, including the Glasgow Haskell
15 Compiler (GHC). The source code for the whole suite is kept in
16 a single CVS repository and shares a common build and
17 installation system.</para>
19 <para>This guide is intended for people who want to build or
20 modify programs from the Glasgow <Literal>fptools</Literal>
21 suite (as distinct from those who merely want to
22 <Emphasis>run</Emphasis> them). Installation instructions are
23 now provided in the user guide.</para>
25 <para>The bulk of this guide applies to building on Unix
26 systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
32 <sect1 id="sec-getting">
33 <title>Getting the sources</title>
35 <para>You can get your hands on the <literal>fptools</literal>
41 <term><indexterm><primary>Source
42 distributions</primary></indexterm>Source distributions</term>
44 <para>You have a supported platform, but (a) you like
45 the warm fuzzy feeling of compiling things yourself;
46 (b) you want to build something ``extra”—e.g., a
47 set of libraries with strictness-analysis turned off; or
48 (c) you want to hack on GHC yourself.</para>
50 <para>A source distribution contains complete sources for
51 one or more projects in the <literal>fptools</literal>
52 suite. Not only that, but the more awkward
53 machine-independent steps are done for you. For example, if
55 <command>happy</command><indexterm><primary>happy</primary></indexterm>
56 you'll find it convenient that the source distribution
57 contains the result of running <command>happy</command> on
58 the parser specifications. If you don't want to alter the
59 parser then this saves you having to find and install
60 <command>happy</command>. You will still need a working
61 version of GHC (preferably version 4.08+) on your machine in
62 order to compile (most of) the sources, however.</para>
67 <term>The CVS repository.</term>
68 <indexterm><primary>CVS repository</primary>
71 <para>We make releases infrequently. If you want more
72 up-to-the minute (but less tested) source code then you need
73 to get access to our CVS repository.</para>
75 <para>All the <literal>fptools</literal> source code is held
76 in a CVS repository. CVS is a pretty good source-code
77 control system, and best of all it works over the
80 <para>The repository holds source code only. It holds no
81 mechanically generated files at all. So if you check out a
82 source tree from CVS you will need to install every utility
83 so that you can build all the derived files from
86 <para>More information about our CVS repository can be found
87 in <xref linkend="sec-cvs">.</para>
92 <para>If you are going to do any building from sources (either
93 from a source distribution or the CVS repository) then you need to
94 read all of this manual in detail.</para>
98 <title>Using the CVS repository</title>
100 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
101 sources for various software projects. CVS lets several people
102 work on the same software at the same time, allowing changes to be
103 checked in incrementally. </para>
105 <para>This section is a set of guidelines for how to use our CVS
106 repository, and will probably evolve in time. The main thing to
107 remember is that most mistakes can be undone, but if there's
108 anything you're not sure about feel free to bug the local CVS
109 meister (namely Jeff Lewis
110 <email>jlewis@galconn.com</email>). </para>
112 <sect2 id="cvs-access">
113 <title>Getting access to the CVS Repository</title>
115 <para>You can access the repository in one of two ways:
116 read-only (<xref linkend="cvs-read-only">), or read-write (<xref
117 linkend="cvs-read-write">).</para>
119 <sect3 id="cvs-read-only">
120 <title>Remote Read-only CVS Access</title>
122 <para>Read-only access is available to anyone - there's no
123 need to ask us first. With read-only CVS access you can do
124 anything except commit changes to the repository. You can
125 make changes to your local tree, and still use CVS's merge
126 facility to keep your tree up to date, and you can generate
127 patches using 'cvs diff' in order to send to us for
130 <para>To get read-only access to the repository:</para>
134 <para>Make sure that <application>cvs</application> is
135 installed on your machine.</para>
138 <para>Set your <literal>$CVSROOT</literal> environment variable to
139 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
142 <para>Run the command</para>
146 <para>The password is simply <literal>cvs</literal>. This
147 sets up a file in your home directory called
148 <literal>.cvspass</literal>, which squirrels away the
149 dummy password, so you only need to do this step once.</para>
153 <para>Now go to <xref linkend="cvs-first">.</para>
158 <sect3 id="cvs-read-write">
159 <title>Remote Read-Write CVS Access</title>
161 <para>We generally supply read-write access to folk doing
162 serious development on some part of the source tree, when
163 going through us would be a pain. If you're developing some
164 feature, or think you have the time and inclination to fix
165 bugs in our sources, feel free to ask for read-write
166 access. There is a certain amount of responsibility that goes
167 with commit privileges; we are more likely to grant you access
168 if you've demonstrated your competence by sending us patches
169 via mail in the past.</para>
171 <para>To get remote read-write CVS access, you need to do the
172 following steps.</para>
176 <para>Make sure that <literal>cvs</literal> and
177 <literal>ssh</literal> are both installed on your
182 <para>Generate a DSA private-key/public-key pair, thus:</para>
186 <para>(<literal>ssh-keygen</literal> comes with
187 <literal>ssh</literal>.) Running <literal>ssh-keygen
188 -d</literal> creates the private and public keys in
189 <literal>$HOME/.ssh/id_dsa</literal> and
190 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
191 (assuming you accept the standard defaults).</para>
193 <para><literal>ssh-keygen -d</literal> will only work if
194 you have Version 2 <literal>ssh</literal> installed; it
195 will fail harmlessly otherwise. If you only have Version
196 1 you can instead generate an RSA key pair using plain</para>
201 <para>Doing so creates the private and public RSA keys in
202 <literal>$HOME/.ssh/identity</literal> and
203 <literal>$HOME/.ssh/identity.pub</literal>
206 <para>[Deprecated.] Incidentally, you can force a Version
207 2 <literal>ssh</literal> to use the Version 1 protocol by
208 creating <literal>$HOME/config</literal> with the
209 following in it:</para>
217 <para>In both cases, <literal>ssh-keygen</literal> will
218 ask for a <firstterm>passphrase</firstterm>. The
219 passphrase is a password that protects your private key.
220 In response to the 'Enter passphrase' question, you can
224 <para>[Recommended.] Enter a passphrase, which you
225 will quote each time you use CVS.
226 <literal>ssh-agent</literal> makes this entirely
230 <para>[Deprecated.] Just hit return (i.e. use an empty
231 passphrase); then you won't need to quote the
232 passphrase when using CVS. The downside is that
233 anyone who can see into your <literal>.ssh</literal>
234 directory, and thereby get your private key, can mess
235 up the repository. So you must keep the
236 <literal>.ssh</literal> directory with draconian
237 no-access permissions.</para>
243 [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
244 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
245 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
246 and run it as follows:
248 c:\tmp> set CYGWIN32=tty
249 c:\tmp> c:/user/local/bin/ssh-keygen1
252 <para>[Windows users.] To protect your
253 <literal>.ssh</literal> from access by anyone else,
254 right-click your <literal>.ssh</literal> directory, and
255 select <literal>Properties</literal>. If you are not on
256 the access control list, add yourself, and give yourself
257 full permissions (the second panel). Remove everyone else
258 from the access control list. Don't leave them there but
259 deny them access, because 'they' may be a list that
264 <para>Send a message to to the CVS repository
265 administrator (currently Jeff Lewis
266 <email>jeff@galconn.com</email>), containing:</para>
269 <para>Your desired user-name.</para>
272 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
273 <literal>.ssh/identity.pub</literal>).</para>
276 <para>He will set up your account.</para>
280 <para>Set the following environment variables:</para>
284 <constant>$HOME</constant>: points to your home directory. This is where CVS
285 will look for its <filename>.cvsrc</filename> file.
291 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
293 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
294 <literal>ssh</literal> assumes that your CVS client
295 understands how to execute shell script
296 ("#!"s,really), which is what
297 <literal>ssh</literal> is. This may not be the case on
298 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
299 <literal>ssh1</literal>.</para>
303 <para><literal>$CVSROOT</literal> to
304 <literal>:ext:</literal><replaceable>your-username</replaceable>
305 <literal>@cvs.haskell.org:/home/cvs/root</literal>
306 where <replaceable>your-username</replaceable> is your user name on
307 <literal>cvs.haskell.org</literal>.
309 <para>The <literal>CVSROOT</literal> environment variable will
310 be recorded in the checked-out tree, so you don't need to set
311 this every time. </para>
317 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
318 if you want to use an Emacs buffer for typing in those long commit messages.
324 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
325 set this to point to <filename>bash.exe</filename>.
336 Put the following in <filename>$HOME/.cvsrc</filename>:
347 These are the default options for the specified CVS commands,
348 and represent better defaults than the usual ones. (Feel
349 free to change them.)
353 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
354 the 8.3 DOS filesystem, but that restriction should have
355 been lifted by now (i.e., you're using VFAT or later filesystems.) If
356 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
364 <para>[Experts.] Once your account is set up, you can get
365 access from other machines without bothering Jeff, thus:</para>
368 <para>Generate a public/private key pair on the new
372 <para>Use ssh to log in to
373 <literal>cvs.haskell.org</literal>, from your old
377 <para>Add the public key for the new machine to the file
378 <literal>$HOME/ssh/authorized_keys</literal> on
379 <literal>cvs.haskell.org</literal>.
380 (<literal>authorized_keys2</literal>, I think, for Version
384 <para>Make sure that the new version of
385 <literal>authorized_keys</literal> still has 600 file
394 <sect2 id="cvs-first">
395 <title>Checking Out a Source Tree</title>
399 <para>Make sure you set your <literal>CVSROOT</literal>
400 environment variable according to either of the remote
401 methods above. The Approved Way to check out a source tree
402 is as follows:</para>
405 $ cvs checkout fpconfig
408 <para>At this point you have a new directory called
409 <literal>fptools</literal> which contains the basic stuff
410 for the fptools suite, including the configuration files and
411 some other junk. </para>
413 <para>[Windows users.] The following messages appear to be harmless:
415 setsockopt IPTOS_LOWDELAY: Invalid argument
416 setsockopt IPTOS_THROUGHPUT: Invalid argument
421 <para>You can call the fptools directory whatever you like,
422 CVS won't mind: </para>
425 $ mv fptools <replaceable>directory</replaceable>
428 <para> NB: after you've read the CVS manual you might be
429 tempted to try</para>
431 $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
434 <para>instead of checking out <literal>fpconfig</literal>
435 and then renaming it. But this doesn't work, and will
436 result in checking out the entire repository instead of just
437 the <literal>fpconfig</literal> bit.</para>
439 $ cd <replaceable>directory</replaceable>
440 $ cvs checkout ghc hslibs libraries
443 <para>The second command here checks out the relevant
444 modules you want to work on. For a GHC build, for instance,
445 you need at least the <literal>ghc</literal>,
446 <literal>hslibs</literal> and <literal>libraries</literal>
447 modules (for a full list of the projects available, see
448 <xref linkend="projects">).</para>
453 <sect2 id="cvs-committing">
454 <title>Committing Changes</title>
456 <para>This is only if you have read-write access to the
457 repository. For anoncvs users, CVS will issue a "read-only
458 repository" error if you try to commit changes.</para>
462 <para>Build the software, if necessary. Unless you're just
463 working on documentation, you'll probably want to build the
464 software in order to test any changes you make.</para>
468 <para>Make changes. Preferably small ones first.</para>
472 <para>Test them. You can see exactly what changes you've
473 made by using the <literal>cvs diff</literal> command:</para>
477 <para>lists all the changes (using the
478 <literal>diff</literal> command) in and below the current
479 directory. In emacs, <literal>C-c C-v =</literal> runs
480 <literal>cvs diff</literal> on the current buffer and shows
481 you the results.</para>
485 <para>Before checking in a change, you need to update your
492 <para>This pulls in any changes that other people have made,
493 and merges them with yours. If there are any conflicts, CVS
494 will tell you, and you'll have to resolve them before you
495 can check your changes in. The documentation describes what
496 to do in the event of a conflict.</para>
498 <para>It's not always necessary to do a full cvs update
499 before checking in a change, since CVS will always tell you
500 if you try to check in a file that someone else has changed.
501 However, you should still update at regular intervals to
502 avoid making changes that don't work in conjuction with
503 changes that someone else made. Keeping an eye on what goes
504 by on the mailing list can help here.</para>
508 <para>When you're happy that your change isn't going to
509 break anything, check it in. For a one-file change:</para>
512 $ cvs commit <replaceable>filename</replaceable>
515 <para>CVS will then pop up an editor for you to enter a
516 "commit message", this is just a short description
517 of what your change does, and will be kept in the history of
520 <para>If you're using emacs, simply load up the file into a
521 buffer and type <literal>C-x C-q</literal>, and emacs will
522 prompt for a commit message and then check in the file for
525 <para>For a multiple-file change, things are a bit
526 trickier. There are several ways to do this, but this is the
527 way I find easiest. First type the commit message into a
528 temporary file. Then either</para>
531 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
534 <para>or, if nothing else has changed in this part of the
538 $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
541 <para>where <replaceable>directory</replaceable> is a common
542 parent directory for all your changes, and
543 <replaceable>commit-message</replaceable> is the name of the
544 file containing the commit message.</para>
546 <para>Shortly afterwards, you'll get some mail from the
547 relevant mailing list saying which files changed, and giving
548 the commit message. For a multiple-file change, you should
549 still get only <emphasis>one</emphasis> message.</para>
554 <sect2 id="cvs-update">
555 <title>Updating Your Source Tree</title>
557 <para>It can be tempting to cvs update just part of a source
558 tree to bring in some changes that someone else has made, or
559 before committing your own changes. This is NOT RECOMMENDED!
560 Quite often changes in one part of the tree are dependent on
561 changes in another part of the tree (the
562 <literal>mk/*.mk</literal> files are a good example where
563 problems crop up quite often). Having an inconsistent tree is a
564 major cause of headaches. </para>
566 <para>So, to avoid a lot of hassle, follow this recipe for
567 updating your tree: </para>
571 $ cvs update -Pd 2>&1 | tee log</screen>
573 <para>Look at the log file, and fix any conflicts (denoted by a
574 <quote>C</quote> in the first column). If you're using multiple
575 build trees, then for every build tree you have pointing at this
576 source tree, you need to update the links in case any new files
577 have appeared: </para>
580 $ cd <replaceable>build-tree</replaceable>
581 $ lndir <replaceable>source-tree</replaceable>
584 <para>Some files might have been removed, so you need to remove
585 the links pointing to these non-existent files:</para>
588 $ find . -xtype l -exec rm '{}' \;
591 <para>To be <emphasis>really</emphasis> safe, you should do
594 <screen>$ gmake all</screen>
596 <para>from the top-level, to update the dependencies and build
597 any changed files. </para>
600 <sect2 id="cvs-tags">
601 <title>GHC Tag Policy</title>
603 <para>If you want to check out a particular version of GHC,
604 you'll need to know how we tag versions in the repository. The
605 policy (as of 4.04) is:</para>
609 <para>The tree is branched before every major release. The
610 branch tag is <literal>ghc-x-xx-branch</literal>, where
611 <literal>x-xx</literal> is the version number of the release
612 with the <literal>'.'</literal> replaced by a
613 <literal>'-'</literal>. For example, the 4.04 release lives
614 on <literal>ghc-4-04-branch</literal>.</para>
618 <para>The release itself is tagged with
619 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
620 called <literal>ghc-4-06</literal>.</para>
624 <para>We didn't always follow these guidelines, so to see
625 what tags there are for previous versions, do <literal>cvs
626 log</literal> on a file that's been around for a while (like
627 <literal>fptools/ghc/README</literal>).</para>
631 <para>So, to check out a fresh GHC 4.06 tree you would
635 $ cvs co -r ghc-4-06 fpconfig
637 $ cvs co -r ghc-4-06 ghc hslibs
641 <sect2 id="cvs-hints">
642 <title>General Hints</title>
646 <para>As a general rule: commit changes in small units,
647 preferably addressing one issue or implementing a single
648 feature. Provide a descriptive log message so that the
649 repository records exactly which changes were required to
650 implement a given feature/fix a bug. I've found this
651 <emphasis>very</emphasis> useful in the past for finding out
652 when a particular bug was introduced: you can just wind back
653 the CVS tree until the bug disappears.</para>
657 <para>Keep the sources at least *buildable* at any given
658 time. No doubt bugs will creep in, but it's quite easy to
659 ensure that any change made at least leaves the tree in a
660 buildable state. We do nightly builds of GHC to keep an eye
661 on what things work/don't work each day and how we're doing
662 in relation to previous verions. This idea is truely wrecked
663 if the compiler won't build in the first place!</para>
667 <para>To check out extra bits into an already-checked-out
668 tree, use the following procedure. Suppose you have a
669 checked-out fptools tree containing just ghc, and you want
670 to add nofib to it:</para>
681 $ cvs update -d nofib
684 <para>(the -d flag tells update to create a new
685 directory). If you just want part of the nofib suite, you
690 $ cvs checkout nofib/spectral
693 <para>This works because <literal>nofib</literal> is a
694 module in its own right, and spectral is a subdirectory of
695 the nofib module. The path argument to checkout must always
696 start with a module name. There's no equivalent form of this
697 command using <literal>update</literal>.</para>
703 <sect1 id="projects">
704 <title>What projects are there?</title>
706 <para>The <literal>fptools</literal> suite consists of several
707 <firstterm>projects</firstterm>, most of which can be downloaded,
708 built and installed individually. Each project corresponds to a
709 subdirectory in the source tree, and if checking out from CVS then
710 each project can be checked out individually by sitting in the top
711 level of your source tree and typing <command>cvs checkout
712 <replaceable>project</replaceable></command>.</para>
714 <para>Here is a list of the projects currently available:</para>
718 <term><literal>ghc</literal></term>
719 <indexterm><primary><literal>ghc</literal></primary>
720 <secondary>project</secondary></indexterm>
722 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
723 Haskell Compiler</ulink> (minus libraries). Absolutely
724 required for building GHC.</para>
729 <term><literal>glafp-utils</literal></term>
730 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
732 <para>Utility programs, some of which are used by the
733 build/installation system. Required for pretty much
739 <term><literal>green-card</literal></term>
740 <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
743 url="http://www.haskell.org/greencard/">Green Card</ulink>
744 system for generating Haskell foreign function
750 <term><literal>haggis</literal></term>
751 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
754 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
755 Haskell GUI framework.</para>
760 <term><literal>haddock</literal></term>
761 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
764 url="http://www.haskell.org/haddock/">Haddock</ulink>
765 documentation tool.</para>
770 <term><literal>happy</literal></term>
771 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
774 url="http://www.haskell.org/happy/">Happy</ulink> Parser
780 <term><literal>hdirect</literal></term>
781 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
784 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
785 Haskell interoperability tool.</para>
790 <term><literal>hood</literal></term>
791 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
793 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
794 Object Observation Debugger</ulink>.</para>
799 <term><literal>hslibs</literal></term>
800 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
802 <para>Supplemental libraries for GHC
803 (<emphasis>required</emphasis> for building GHC).</para>
808 <term><literal>libraries</literal></term>
809 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
811 <para>Hierarchical Haskell library suite
812 (<emphasis>required</emphasis> for building GHC).</para>
817 <term><literal>mhms</literal></term>
818 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
820 <para>The Modular Haskell Metric System.</para>
825 <term><literal>nofib</literal></term>
826 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
828 <para>The NoFib suite: A collection of Haskell programs used
829 primarily for benchmarking.</para>
834 <term><literal>testsuite</literal></term>
835 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
837 <para>A testing framework, including GHC's regression test
843 <para>So, to build GHC you need at least the
844 <literal>ghc</literal>, <literal>libraries</literal> and
845 <literal>hslibs</literal> projects (a GHC source distribution will
846 already include the bits you need).</para>
849 <sect1 id="sec-build-checks">
850 <title>Things to check before you start</title>
852 <para>Here's a list of things to check before you get
858 <indexterm><primary>Disk space needed</primary></indexterm>
859 <para>Disk space needed: from about 100Mb for a basic GHC
860 build, up to probably 500Mb for a GHC build with everything
861 included (libraries built several different ways,
866 <para>Use an appropriate machine / operating system. <xref
867 linkend="sec-port-info"> lists the supported platforms; if
868 yours isn't amongst these then you can try porting GHC (see
869 <xref linkend="sec-porting-ghc">).</para>
873 <para>Be sure that the “pre-supposed” utilities are
874 installed. <Xref LinkEnd="sec-pre-supposed">
879 <para>If you have any problem when building or installing the
880 Glasgow tools, please check the “known pitfalls” (<Xref
881 LinkEnd="sec-build-pitfalls">). Also check the FAQ for the
882 version you're building, which is part of the User's Guide and
883 available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
886 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
888 <para>If you feel there is still some shortcoming in our
889 procedure or instructions, please report it.</para>
891 <para>For GHC, please see the <ulink
892 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
893 section of the GHC Users' Guide</ulink>, to maximise the
894 usefulness of your report.</para>
896 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
897 <para>If in doubt, please send a message to
898 <email>glasgow-haskell-bugs@haskell.org</email>.
899 <indexterm><primary>bugs</primary><secondary>mailing
900 list</secondary></indexterm></para>
905 <sect1 id="sec-port-info">
906 <title>What machines the Glasgow tools run on</title>
908 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
909 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
910 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
912 <para>The main question is whether or not the Haskell compiler
913 (GHC) runs on your platform.</para>
915 <para>A “platform” is a
916 architecture/manufacturer/operating-system combination, such as
917 <literal>sparc-sun-solaris2</literal>. Other common ones are
918 <literal>alpha-dec-osf2</literal>,
919 <literal>hppa1.1-hp-hpux9</literal>,
920 <literal>i386-unknown-linux</literal>,
921 <literal>i386-unknown-solaris2</literal>,
922 <literal>i386-unknown-freebsd</literal>,
923 <literal>i386-unknown-cygwin32</literal>,
924 <literal>m68k-sun-sunos4</literal>,
925 <literal>mips-sgi-irix5</literal>,
926 <literal>sparc-sun-sunos4</literal>,
927 <literal>sparc-sun-solaris2</literal>,
928 <literal>powerpc-ibm-aix</literal>.</para>
930 <para>Some libraries may only work on a limited number of
931 platforms; for example, a sockets library is of no use unless the
932 operating system supports the underlying BSDisms.</para>
935 <title>What platforms the Haskell compiler (GHC) runs on</title>
937 <indexterm><primary>fully-supported platforms</primary></indexterm>
938 <indexterm><primary>native-code generator</primary></indexterm>
939 <indexterm><primary>registerised ports</primary></indexterm>
940 <indexterm><primary>unregisterised ports</primary></indexterm>
942 <para>The GHC hierarchy of Porting Goodness: (a) Best is a
943 native-code generator; (b) next best is a
944 “registerised” port; (c) the bare minimum is an
945 “unregisterised” port.
946 (“Unregisterised” is so terrible that we won't say
947 more about it).</para>
949 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
950 FreeBSD and Linux, so those are the best supported platforms,
951 unsurprisingly.</para>
953 <para>Here's everything that's known about GHC ports. We
954 identify platforms by their “canonical”
955 CPU/Manufacturer/OS triple.</para>
959 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
960 <indexterm><primary>alpha-dec-osf</primary></indexterm>
961 <indexterm><primary>alpha-dec-linux</primary></indexterm>
962 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
963 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
964 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
967 <para>The OSF port is currently working (as of GHC version
968 5.02.1) and well supported. The native code generator is
969 currently non-working. Other operating systems will
970 require some minor porting.</para>
975 <term>sparc-sun-sunos4</term>
976 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
978 <para>Probably works with minor tweaks, hasn't been tested
984 <term>sparc-sun-solaris2</term>
985 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
987 <para>Fully supported (at least for Solaris 2.7),
988 including native-code generator.</para>
993 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
994 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
996 <para>A registerised port is available for version 4.08,
997 but GHC hasn't been built on that platform since (as far
998 as we know). No native-code generator.</para>
1003 <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
1004 <indexterm><primary>i386-*-linux</primary></indexterm>
1006 <para>GHC works registerised and has a native code
1007 generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
1008 or later. NOTE about <literal>glibc</literal> versions:
1009 GHC binaries built on a system running <literal>glibc
1010 2.0</literal> won't work on a system running
1011 <literal>glibc 2.1</literal>, and vice versa. In general,
1012 don't expect compatibility between
1013 <literal>glibc</literal> versions, even if the shared
1014 library version hasn't changed.</para>
1019 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
1021 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1023 <para>GHC works registerised. Pre-built packages are
1024 available in the native package format, so if you just
1025 need binaries you're better off just installing the
1026 package (it might even be on your installation
1032 <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
1033 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1035 <para>Supported, with native code generator. Packages are
1036 available through the ports system in the native package
1042 <term>i386-unknown-netbsd (PCs running NetBSD and
1044 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1046 <para>Will require some minor porting effort, but should
1047 work registerised.</para>
1052 <term>i386-unknown-mingw32 (PCs running Windows)</term>
1053 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1055 <para>Fully supported under Win9x, WinNT, Win2k, and
1056 WinXP. Includes a native code generator. Building from
1057 source requires a recent <ulink
1058 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1059 to be installed.</para>
1064 <term>ia64-unknown-linux</term>
1065 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1067 <para>GHC currently works unregisterised. A registerised
1068 port is in progress.</para>
1073 <term>mips-sgi-irix5</term>
1074 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1076 <para>Port has worked in the past, but hasn't been tested
1077 for some time (and will certainly have rotted in various
1078 ways). As usual, we don't have access to machines and
1079 there hasn't been an overwhelming demand for this port,
1080 but feel free to get in touch.</para>
1085 <term>powerpc-ibm-aix</term>
1086 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1088 <para>Port currently doesn't work, needs some minimal
1089 porting effort. As usual, we don't have access to
1090 machines and there hasn't been an overwhelming demand for
1091 this port, but feel free to get in touch.</para>
1096 <term>powerpc-apple-darwin</term>
1097 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1099 <para>Supported registerised. No native code
1105 <term>powerpc-apple-linux</term>
1106 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1108 <para>Not supported (yet).</para>
1113 <para>Various other systems have had GHC ported to them in the
1114 distant past, including various Motorola 68k boxes. The 68k
1115 support still remains, but porting to one of these systems will
1116 certainly be a non-trivial task.</para>
1120 <title>What machines the other tools run on</title>
1122 <para>Unless you hear otherwise, the other tools work if GHC
1128 <sect1 id="sec-pre-supposed">
1129 <title>Installing pre-supposed utilities</title>
1131 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1132 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1134 <para>Here are the gory details about some utility programs you
1135 may need; <command>perl</command>, <command>gcc</command> and
1136 <command>happy</command> are the only important
1137 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1138 important if you're going for Parallel Haskell.) The
1139 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1140 script will tell you if you are missing something.</para>
1146 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1147 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1149 <para><emphasis>You have to have Perl to proceed!</emphasis>
1150 Perl version 5 at least is required. GHC has been known to
1151 tickle bugs in Perl, so if you find that Perl crashes when
1152 running GHC try updating (or downgrading) your Perl
1153 installation. Versions of Perl that we use and are known to
1154 be fairly stable are 5.005 and 5.6.1.</para>
1156 <para>For Win32 platforms, you should use the binary
1157 supplied in the InstallShield (copy it to
1158 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1161 <para>Perl should be put somewhere so that it can be invoked
1162 by the <literal>#!</literal> script-invoking
1163 mechanism. The full pathname may need to be less than 32
1164 characters long on some systems.</para>
1169 <term>GNU C (<command>gcc</command>)</term>
1170 <indexterm><primary>pre-supposed: GCC (GNU C
1171 compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
1172 compiler), pre-supposed</primary></indexterm>
1174 <para>We recommend using GCC version 2.95.2 on all
1175 platforms. Failing that, version 2.7.2 is stable on most
1176 platforms. Earlier versions of GCC can be assumed not to
1177 work, and versions in between 2.7.2 and 2.95.2 (including
1178 <command>egcs</command>) have varying degrees of stability
1179 depending on the platform.</para>
1181 <para>If your GCC dies with “internal error” on
1182 some GHC source file, please let us know, so we can report
1183 it and get things improved. (Exception: on iX86
1184 boxes—you may need to fiddle with GHC's
1185 <option>-monly-N-regs</option> option; see the User's
1191 <term>GNU Make</term>
1192 <indexterm><primary>make</primary><secondary>GNU</secondary>
1195 <para>The fptools build system makes heavy use of features
1196 specific to GNU <command>make</command>, so you must have
1197 this installed in order to build any of the fptools
1204 <indexterm><primary>Happy</primary></indexterm>
1206 <para>Happy is a parser generator tool for Haskell, and is
1207 used to generate GHC's parsers. Happy is written in
1208 Haskell, and is a project in the CVS repository
1209 (<literal>fptools/happy</literal>). It can be built from
1210 source, but bear in mind that you'll need GHC installed in
1211 order to build it. To avoid the chicken/egg problem,
1212 install a binary distribtion of either Happy or GHC to get
1213 started. Happy distributions are available from <ulink
1214 url="http://www.haskell.org/happy/">Happy's Web
1215 Page</ulink>.</para>
1220 <term>Autoconf</term>
1221 <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
1222 <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
1224 <para>GNU Autoconf is needed if you intend to build from the
1225 CVS sources, it is <emphasis>not</emphasis> needed if you
1226 just intend to build a standard source distribution.</para>
1228 <para>Autoconf builds the <command>configure</command>
1229 script from <filename>configure.in</filename> and
1230 <filename>aclocal.m4</filename>. If you modify either of
1231 these files, you'll need <command>autoconf</command> to
1232 rebuild <filename>configure</filename>.</para>
1237 <term><command>sed</command></term>
1238 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1239 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1241 <para>You need a working <command>sed</command> if you are
1242 going to build from sources. The build-configuration stuff
1243 needs it. GNU sed version 2.0.4 is no good! It has a bug
1244 in it that is tickled by the build-configuration. 2.0.5 is
1245 OK. Others are probably OK too (assuming we don't create too
1246 elaborate configure scripts.)</para>
1251 <para>One <literal>fptools</literal> project is worth a quick note
1252 at this point, because it is useful for all the others:
1253 <literal>glafp-utils</literal> contains several utilities which
1254 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1255 Like <command>lndir</command> for creating symbolic link
1258 <sect2 id="pre-supposed-gph-tools">
1259 <title>Tools for building parallel GHC (GPH)</title>
1263 <term>PVM version 3:</term>
1264 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1265 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1267 <para>PVM is the Parallel Virtual Machine on which
1268 Parallel Haskell programs run. (You only need this if you
1269 plan to run Parallel Haskell. Concurent Haskell, which
1270 runs concurrent threads on a uniprocessor doesn't need
1271 it.) Underneath PVM, you can have (for example) a network
1272 of workstations (slow) or a multiprocessor box
1275 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1276 It is readily available on the net; I think I got it from
1277 <literal>research.att.com</literal>, in
1278 <filename>netlib</filename>.</para>
1280 <para>A PVM installation is slightly quirky, but easy to
1281 do. Just follow the <filename>Readme</filename>
1282 instructions.</para>
1287 <term><command>bash</command>:</term>
1288 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1290 <para>Sadly, the <command>gr2ps</command> script, used to
1291 convert “parallelism profiles” to PostScript,
1292 is written in Bash (GNU's Bourne Again shell). This bug
1293 will be fixed (someday).</para>
1299 <sect2 id="pre-supposed-other-tools">
1300 <title>Other useful tools</title>
1305 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1306 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1308 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1309 to build a couple of utilities in
1310 <literal>glafp-utils</literal>. Depending on your
1311 operating system, the supplied <command>lex</command> may
1312 or may not work; you should get the GNU version.</para>
1317 <para>More tools are required if you want to format the documentation
1318 that comes with GHC and other fptools projects. See <xref
1319 linkend="building-docs">.</para>
1323 <sect1 id="sec-building-from-source">
1324 <title>Building from source</title>
1326 <indexterm><primary>Building from source</primary></indexterm>
1327 <indexterm><primary>Source, building from</primary></indexterm>
1329 <para>You've been rash enough to want to build some of the Glasgow
1330 Functional Programming tools (GHC, Happy, nofib, etc.) from
1331 source. You've slurped the source, from the CVS repository or
1332 from a source distribution, and now you're sitting looking at a
1333 huge mound of bits, wondering what to do next.</para>
1335 <para>Gingerly, you type <command>make</command>. Wrong
1338 <para>This rest of this guide is intended for duffers like me, who
1339 aren't really interested in Makefiles and systems configurations,
1340 but who need a mental model of the interlocking pieces so that
1341 they can make them work, extend them consistently when adding new
1342 software, and lay hands on them gently when they don't
1345 <sect2 id="sec-source-tree">
1346 <title>Your source tree</title>
1348 <para>The source code is held in your <emphasis>source
1349 tree</emphasis>. The root directory of your source tree
1350 <emphasis>must</emphasis> contain the following directories and
1355 <para><filename>Makefile</filename>: the root
1360 <para><filename>mk/</filename>: the directory that contains
1361 the main Makefile code, shared by all the
1362 <literal>fptools</literal> software.</para>
1366 <para><filename>configure.in</filename>,
1367 <filename>config.sub</filename>,
1368 <filename>config.guess</filename>: these files support the
1369 configuration process.</para>
1373 <para><filename>install-sh</filename>.</para>
1377 <para>All the other directories are individual
1378 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1379 system—for example, the Glasgow Haskell Compiler
1380 (<literal>ghc</literal>), the Happy parser generator
1381 (<literal>happy</literal>), the <literal>nofib</literal>
1382 benchmark suite, and so on. You can have zero or more of these.
1383 Needless to say, some of them are needed to build others.</para>
1385 <para>The important thing to remember is that even if you want
1386 only one project (<literal>happy</literal>, say), you must have
1387 a source tree whose root directory contains
1388 <filename>Makefile</filename>, <filename>mk/</filename>,
1389 <filename>configure.in</filename>, and the project(s) you want
1390 (<filename>happy/</filename> in this case). You cannot get by
1391 with just the <filename>happy/</filename> directory.</para>
1395 <title>Build trees</title>
1396 <indexterm><primary>build trees</primary></indexterm>
1397 <indexterm><primary>link trees, for building</primary></indexterm>
1399 <para>If you just want to build the software once on a single
1400 platform, then your source tree can also be your build tree, and
1401 you can skip the rest of this section.</para>
1403 <para>We often want to build multiple versions of our software
1404 for different architectures, or with different options
1405 (e.g. profiling). It's very desirable to share a single copy of
1406 the source code among all these builds.</para>
1408 <para>So for every source tree we have zero or more
1409 <emphasis>build trees</emphasis>. Each build tree is initially
1410 an exact copy of the source tree, except that each file is a
1411 symbolic link to the source file, rather than being a copy of
1412 the source file. There are “standard” Unix
1413 utilities that make such copies, so standard that they go by
1415 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1416 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1417 are two (If you don't have either, the source distribution
1418 includes sources for the X11
1419 <command>lndir</command>—check out
1420 <filename>fptools/glafp-utils/lndir</filename>). See <Xref
1421 LinkEnd="sec-storysofar"> for a typical invocation.</para>
1423 <para>The build tree does not need to be anywhere near the
1424 source tree in the file system. Indeed, one advantage of
1425 separating the build tree from the source is that the build tree
1426 can be placed in a non-backed-up partition, saving your systems
1427 support people from backing up untold megabytes of
1428 easily-regenerated, and rapidly-changing, gubbins. The golden
1429 rule is that (with a single exception—<XRef
1430 LinkEnd="sec-build-config">) <emphasis>absolutely everything in
1431 the build tree is either a symbolic link to the source tree, or
1432 else is mechanically generated</emphasis>. It should be
1433 perfectly OK for your build tree to vanish overnight; an hour or
1434 two compiling and you're on the road again.</para>
1436 <para>You need to be a bit careful, though, that any new files
1437 you create (if you do any development work) are in the source
1438 tree, not a build tree!</para>
1440 <para>Remember, that the source files in the build tree are
1441 <emphasis>symbolic links</emphasis> to the files in the source
1442 tree. (The build tree soon accumulates lots of built files like
1443 <filename>Foo.o</filename>, as well.) You can
1444 <emphasis>delete</emphasis> a source file from the build tree
1445 without affecting the source tree (though it's an odd thing to
1446 do). On the other hand, if you <emphasis>edit</emphasis> a
1447 source file from the build tree, you'll edit the source-tree
1448 file directly. (You can set up Emacs so that if you edit a
1449 source file from the build tree, Emacs will silently create an
1450 edited copy of the source file in the build tree, leaving the
1451 source file unchanged; but the danger is that you think you've
1452 edited the source file whereas actually all you've done is edit
1453 the build-tree copy. More commonly you do want to edit the
1454 source file.)</para>
1456 <para>Like the source tree, the top level of your build tree
1457 must be (a linked copy of) the root directory of the
1458 <literal>fptools</literal> suite. Inside Makefiles, the root of
1459 your build tree is called
1460 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
1461 In the rest of this document path names are relative to
1462 <constant>$(FPTOOLS_TOP)</constant> unless
1463 otherwise stated. For example, the file
1464 <filename>ghc/mk/target.mk</filename> is actually
1465 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
1468 <sect2 id="sec-build-config">
1469 <title>Getting the build you want</title>
1471 <para>When you build <literal>fptools</literal> you will be
1472 compiling code on a particular <emphasis>host
1473 platform</emphasis>, to run on a particular <emphasis>target
1474 platform</emphasis> (usually the same as the host
1475 platform)<indexterm><primary>platform</primary></indexterm>.
1476 The difficulty is that there are minor differences between
1477 different platforms; minor, but enough that the code needs to be
1478 a bit different for each. There are some big differences too:
1479 for a different architecture we need to build GHC with a
1480 different native-code generator.</para>
1482 <para>There are also knobs you can turn to control how the
1483 <literal>fptools</literal> software is built. For example, you
1484 might want to build GHC optimised (so that it runs fast) or
1485 unoptimised (so that you can compile it fast after you've
1486 modified it. Or, you might want to compile it with debugging on
1487 (so that extra consistency-checking code gets included) or off.
1490 <para>All of this stuff is called the
1491 <emphasis>configuration</emphasis> of your build. You set the
1492 configuration using a three-step process.</para>
1496 <term>Step 1: get ready for configuration.</term>
1498 <para>Change directory to
1499 <constant>$(FPTOOLS_TOP)</constant> and
1501 <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
1502 (with no arguments). This GNU program converts
1503 <filename><constant>$(FPTOOLS_TOP)</constant>/configure.in</filename>
1504 to a shell script called
1505 <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
1508 <para>Some projects, including GHC, have their own
1509 configure script. If there's an
1510 <constant>$(FPTOOLS_TOP)/<project>/configure.in</constant>,
1511 then you need to run <command>autoconf</command> in that
1512 directory too.</para>
1514 <para>Both these steps are completely
1515 platform-independent; they just mean that the
1516 human-written file (<filename>configure.in</filename>) can
1517 be short, although the resulting shell script,
1518 <command>configure</command>, and
1519 <filename>mk/config.h.in</filename>, are long.</para>
1521 <para>In case you don't have <command>autoconf</command>
1522 we distribute the results, <command>configure</command>,
1523 and <filename>mk/config.h.in</filename>, with the source
1524 distribution. They aren't kept in the repository,
1530 <term>Step 2: system configuration.</term>
1532 <para>Runs the newly-created <command>configure</command>
1533 script, thus:</para>
1536 ./configure <optional><parameter>args</parameter></optional>
1539 <para><command>configure</command>'s mission is to scurry
1540 round your computer working out what architecture it has,
1541 what operating system, whether it has the
1542 <Function>vfork</Function> system call, where
1543 <command>yacc</command> is kept, whether
1544 <command>gcc</command> is available, where various obscure
1545 <literal>#include</literal> files are, whether it's a
1546 leap year, and what the systems manager had for lunch. It
1547 communicates these snippets of information in two
1554 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1556 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1557 substituting for things between
1558 “<literal>@</literal>” brackets. So,
1559 “<literal>@HaveGcc@</literal>” will be
1560 replaced by “<literal>YES</literal>” or
1561 “<literal>NO</literal>” depending on what
1562 <command>configure</command> finds.
1563 <filename>mk/config.mk</filename> is included by every
1564 Makefile (directly or indirectly), so the
1565 configuration information is thereby communicated to
1566 all Makefiles.</para>
1570 <para> It translates
1571 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1573 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1574 The latter is <literal>#include</literal>d by
1575 various C programs, which can thereby make use of
1576 configuration information.</para>
1580 <para><command>configure</command> takes some optional
1581 arguments. Use <literal>./configure --help</literal> to
1582 get a list of the available arguments. Here are some of
1583 the ones you might need:</para>
1587 <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
1588 <indexterm><primary><literal>--with-ghc</literal></primary>
1591 <para>Specifies the path to an installed GHC which
1592 you would like to use. This compiler will be used
1593 for compiling GHC-specific code (eg. GHC itself).
1594 This option <emphasis>cannot</emphasis> be specified
1595 using <filename>build.mk</filename> (see later),
1596 because <command>configure</command> needs to
1597 auto-detect the version of GHC you're using. The
1598 default is to look for a compiler named
1599 <literal>ghc</literal> in your path.</para>
1604 <term><literal>--with-hc=<parameter>path</parameter></literal></term>
1605 <indexterm><primary><literal>--with-hc</literal></primary>
1608 <para>Specifies the path to any installed Haskell
1609 compiler. This compiler will be used for compiling
1610 generic Haskell code. The default is to use
1611 <literal>ghc</literal>.</para>
1616 <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
1617 <indexterm><primary><literal>--with-gcc</literal></primary>
1620 <para>Specifies the path to the installed GCC. This
1621 compiler will be used to compile all C files,
1622 <emphasis>except</emphasis> any generated by the
1623 installed Haskell compiler, which will have its own
1624 idea of which C compiler (if any) to use. The
1625 default is to use <literal>gcc</literal>.</para>
1630 <para><command>configure</command> caches the results of
1631 its run in <filename>config.cache</filename>. Quite often
1632 you don't want that; you're running
1633 <command>configure</command> a second time because
1634 something has changed. In that case, simply delete
1635 <filename>config.cache</filename>.</para>
1640 <term>Step 3: build configuration.</term>
1642 <para>Next, you say how this build of
1643 <literal>fptools</literal> is to differ from the standard
1644 defaults by creating a new file
1645 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1646 <emphasis>in the build tree</emphasis>. This file is the
1647 one and only file you edit in the build tree, precisely
1648 because it says how this build differs from the source.
1649 (Just in case your build tree does die, you might want to
1650 keep a private directory of <filename>build.mk</filename>
1651 files, and use a symbolic link in each build tree to point
1652 to the appropriate one.) So
1653 <filename>mk/build.mk</filename> never exists in the
1654 source tree—you create one in each build tree from
1655 the template. We'll discuss what to put in it
1661 <para>And that's it for configuration. Simple, eh?</para>
1663 <para>What do you put in your build-specific configuration file
1664 <filename>mk/build.mk</filename>? <emphasis>For almost all
1665 purposes all you will do is put make variable definitions that
1666 override those in</emphasis>
1667 <filename>mk/config.mk.in</filename>. The whole point of
1668 <filename>mk/config.mk.in</filename>—and its derived
1669 counterpart <filename>mk/config.mk</filename>—is to define
1670 the build configuration. It is heavily commented, as you will
1671 see if you look at it. So generally, what you do is look at
1672 <filename>mk/config.mk.in</filename>, and add definitions in
1673 <filename>mk/build.mk</filename> that override any of the
1674 <filename>config.mk</filename> definitions that you want to
1675 change. (The override occurs because the main boilerplate file,
1676 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1677 includes <filename>build.mk</filename> after
1678 <filename>config.mk</filename>.)</para>
1680 <para>For example, <filename>config.mk.in</filename> contains
1681 the definition:</para>
1684 GhcHcOpts=-O -Rghc-timing
1687 <para>The accompanying comment explains that this is the list of
1688 flags passed to GHC when building GHC itself. For doing
1689 development, it is wise to add <literal>-DDEBUG</literal>, to
1690 enable debugging code. So you would add the following to
1691 <filename>build.mk</filename>:</para>
1693 <para>or, if you prefer,</para>
1696 GhcHcOpts += -DDEBUG
1699 <para>GNU <command>make</command> allows existing definitions to
1700 have new text appended using the “<literal>+=</literal>”
1701 operator, which is quite a convenient feature.)</para>
1703 <para>If you want to remove the <literal>-O</literal> as well (a
1704 good idea when developing, because the turn-around cycle gets a
1705 lot quicker), you can just override
1706 <literal>GhcLibHcOpts</literal> altogether:</para>
1709 GhcHcOpts=-DDEBUG -Rghc-timing
1712 <para>When reading <filename>config.mk.in</filename>, remember
1713 that anything between “@...@” signs is going to be substituted
1714 by <command>configure</command> later. You
1715 <emphasis>can</emphasis> override the resulting definition if
1716 you want, but you need to be a bit surer what you are doing.
1717 For example, there's a line that says:</para>
1723 <para>This defines the Make variables <constant>YACC</constant>
1724 to the pathname for a <command>yacc</command> that
1725 <command>configure</command> finds somewhere. If you have your
1726 own pet <command>yacc</command> you want to use instead, that's
1727 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1733 <para>You do not <emphasis>have</emphasis> to have a
1734 <filename>mk/build.mk</filename> file at all; if you don't,
1735 you'll get all the default settings from
1736 <filename>mk/config.mk.in</filename>.</para>
1738 <para>You can also use <filename>build.mk</filename> to override
1739 anything that <command>configure</command> got wrong. One place
1740 where this happens often is with the definition of
1741 <constant>FPTOOLS_TOP_ABS</constant>: this
1742 variable is supposed to be the canonical path to the top of your
1743 source tree, but if your system uses an automounter then the
1744 correct directory is hard to find automatically. If you find
1745 that <command>configure</command> has got it wrong, just put the
1746 correct definition in <filename>build.mk</filename>.</para>
1750 <sect2 id="sec-storysofar">
1751 <title>The story so far</title>
1753 <para>Let's summarise the steps you need to carry to get
1754 yourself a fully-configured build tree from scratch.</para>
1758 <para> Get your source tree from somewhere (CVS repository
1759 or source distribution). Say you call the root directory
1760 <filename>myfptools</filename> (it does not have to be
1761 called <filename>fptools</filename>). Make sure that you
1762 have the essential files (see <XRef
1763 LinkEnd="sec-source-tree">).</para>
1768 <para>(Optional) Use <command>lndir</command> or
1769 <command>mkshadowdir</command> to create a build tree.</para>
1773 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1776 <para>(N.B. <command>mkshadowdir</command>'s first argument
1777 is taken relative to its second.) You probably want to give
1778 the build tree a name that suggests its main defining
1779 characteristic (in your mind at least), in case you later
1784 <para>Change directory to the build tree. Everything is
1785 going to happen there now.</para>
1788 $ cd /scratch/joe-bloggs/myfptools-sun4
1794 <para>Prepare for system configuration:</para>
1800 <para>(You can skip this step if you are starting from a
1801 source distribution, and you already have
1802 <filename>configure</filename> and
1803 <filename>mk/config.h.in</filename>.)</para>
1805 <para>Some projects, including GHC itself, have their own
1806 configure scripts, so it is necessary to run autoconf again
1807 in the appropriate subdirectories. eg:</para>
1810 $ (cd ghc; autoconf)
1815 <para>Do system configuration:</para>
1821 <para>Don't forget to check whether you need to add any
1822 arguments to <literal>configure</literal>; for example, a
1823 common requirement is to specify which GHC to use with
1824 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1828 <para>Create the file <filename>mk/build.mk</filename>,
1829 adding definitions for your desired configuration
1838 <para>You can make subsequent changes to
1839 <filename>mk/build.mk</filename> as often as you like. You do
1840 not have to run any further configuration programs to make these
1841 changes take effect. In theory you should, however, say
1842 <command>gmake clean</command>, <command>gmake all</command>,
1843 because configuration option changes could affect
1844 anything—but in practice you are likely to know what's
1849 <title>Making things</title>
1851 <para>At this point you have made yourself a fully-configured
1852 build tree, so you are ready to start building real
1855 <para>The first thing you need to know is that <emphasis>you
1856 must use GNU <command>make</command>, usually called
1857 <command>gmake</command>, not standard Unix
1858 <command>make</command></emphasis>. If you use standard Unix
1859 <command>make</command> you will get all sorts of error messages
1860 (but no damage) because the <literal>fptools</literal>
1861 <command>Makefiles</command> use GNU <command>make</command>'s
1862 facilities extensively.</para>
1864 <para>To just build the whole thing, <command>cd</command> to
1865 the top of your <literal>fptools</literal> tree and type
1866 <command>gmake</command>. This will prepare the tree and build
1867 the various projects in the correct order.</para>
1871 <sect2 id="sec-standard-targets">
1872 <title>Standard Targets</title>
1873 <indexterm><primary>targets, standard makefile</primary></indexterm>
1874 <indexterm><primary>makefile targets</primary></indexterm>
1876 <para>In any directory you should be able to make the following:</para>
1880 <term><literal>boot</literal></term>
1882 <para>does the one-off preparation required to get ready
1883 for the real work. Notably, it does <command>gmake
1884 depend</command> in all directories that contain programs.
1885 It also builds the necessary tools for compilation to
1888 <para>Invoking the <literal>boot</literal> target
1889 explicitly is not normally necessary. From the top-level
1890 <literal>fptools</literal> directory, invoking
1891 <literal>gmake</literal> causes <literal>gmake boot
1892 all</literal> to be invoked in each of the project
1893 subdirectories, in the order specified by
1894 <literal>$(AllTargets)</literal> in
1895 <literal>config.mk</literal>.</para>
1897 <para>If you're working in a subdirectory somewhere and
1898 need to update the dependencies, <literal>gmake
1899 boot</literal> is a good way to do it.</para>
1904 <term><literal>all</literal></term>
1906 <para>makes all the final target(s) for this Makefile.
1907 Depending on which directory you are in a “final
1908 target” may be an executable program, a library
1909 archive, a shell script, or a Postscript file. Typing
1910 <command>gmake</command> alone is generally the same as
1911 typing <command>gmake all</command>.</para>
1916 <term><literal>install</literal></term>
1918 <para>installs the things built by <literal>all</literal>
1919 (except for the documentation). Where does it install
1920 them? That is specified by
1921 <filename>mk/config.mk.in</filename>; you can override it
1922 in <filename>mk/build.mk</filename>, or by running
1923 <command>configure</command> with command-line arguments
1924 like <literal>--bindir=/home/simonpj/bin</literal>; see
1925 <literal>./configure --help</literal> for the full
1931 <term><literal>install-docs</literal></term>
1933 <para>installs the documentation. Otherwise behaves just
1934 like <literal>install</literal>.</para>
1939 <term><literal>uninstall</literal></term>
1941 <para>reverses the effect of
1942 <literal>install</literal>.</para>
1947 <term><literal>clean</literal></term>
1949 <para>Delete all files from the current directory that are
1950 normally created by building the program. Don't delete
1951 the files that record the configuration, or files
1952 generated by <command>gmake boot</command>. Also preserve
1953 files that could be made by building, but normally aren't
1954 because the distribution comes with them.</para>
1959 <term><literal>distclean</literal></term>
1961 <para>Delete all files from the current directory that are
1962 created by configuring or building the program. If you
1963 have unpacked the source and built the program without
1964 creating any other files, <literal>make
1965 distclean</literal> should leave only the files that were
1966 in the distribution.</para>
1971 <term><literal>mostlyclean</literal></term>
1973 <para>Like <literal>clean</literal>, but may refrain from
1974 deleting a few files that people normally don't want to
1980 <term><literal>maintainer-clean</literal></term>
1982 <para>Delete everything from the current directory that
1983 can be reconstructed with this Makefile. This typically
1984 includes everything deleted by
1985 <literal>distclean</literal>, plus more: C source files
1986 produced by Bison, tags tables, Info files, and so
1989 <para>One exception, however: <literal>make
1990 maintainer-clean</literal> should not delete
1991 <filename>configure</filename> even if
1992 <filename>configure</filename> can be remade using a rule
1993 in the <filename>Makefile</filename>. More generally,
1994 <literal>make maintainer-clean</literal> should not delete
1995 anything that needs to exist in order to run
1996 <filename>configure</filename> and then begin to build the
2002 <term><literal>check</literal></term>
2004 <para>run the test suite.</para>
2009 <para>All of these standard targets automatically recurse into
2010 sub-directories. Certain other standard targets do not:</para>
2014 <term><literal>configure</literal></term>
2016 <para>is only available in the root directory
2017 <constant>$(FPTOOLS_TOP)</constant>; it has
2018 been discussed in <XRef
2019 LinkEnd="sec-build-config">.</para>
2024 <term><literal>depend</literal></term>
2026 <para>make a <filename>.depend</filename> file in each
2027 directory that needs it. This <filename>.depend</filename>
2028 file contains mechanically-generated dependency
2029 information; for example, suppose a directory contains a
2030 Haskell source module <filename>Foo.lhs</filename> which
2031 imports another module <literal>Baz</literal>. Then the
2032 generated <filename>.depend</filename> file will contain
2033 the dependency:</para>
2039 <para>which says that the object file
2040 <filename>Foo.o</filename> depends on the interface file
2041 <filename>Baz.hi</filename> generated by compiling module
2042 <literal>Baz</literal>. The <filename>.depend</filename>
2043 file is automatically included by every Makefile.</para>
2048 <term><literal>binary-dist</literal></term>
2050 <para>make a binary distribution. This is the target we
2051 use to build the binary distributions of GHC and
2057 <term><literal>dist</literal></term>
2059 <para>make a source distribution. Note that this target
2060 does “make distclean” as part of its work;
2061 don't use it if you want to keep what you've built.</para>
2066 <para>Most <filename>Makefile</filename>s have targets other
2067 than these. You can discover them by looking in the
2068 <filename>Makefile</filename> itself.</para>
2072 <title>Using a project from the build tree</title>
2074 <para>If you want to build GHC (say) and just use it direct from
2075 the build tree without doing <literal>make install</literal>
2076 first, you can run the in-place driver script:
2077 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2079 <para> Do <emphasis>NOT</emphasis> use
2080 <filename>ghc/compiler/ghc</filename>, or
2081 <filename>ghc/compiler/ghc-5.xx</filename>, as these are the
2082 scripts intended for installation, and contain hard-wired paths
2083 to the installed libraries, rather than the libraries in the
2086 <para>Happy can similarly be run from the build tree, using
2087 <filename>happy/src/happy-inplace</filename>.</para>
2091 <title>Fast Making</title>
2093 <indexterm><primary>fastmake</primary></indexterm>
2094 <indexterm><primary>dependencies, omitting</primary></indexterm>
2095 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2097 <para>Sometimes the dependencies get in the way: if you've made
2098 a small change to one file, and you're absolutely sure that it
2099 won't affect anything else, but you know that
2100 <command>make</command> is going to rebuild everything anyway,
2101 the following hack may be useful:</para>
2107 <para>This tells the make system to ignore dependencies and just
2108 build what you tell it to. In other words, it's equivalent to
2109 temporarily removing the <filename>.depend</filename> file in
2110 the current directory (where <command>mkdependHS</command> and
2111 friends store their dependency information).</para>
2113 <para>A bit of history: GHC used to come with a
2114 <command>fastmake</command> script that did the above job, but
2115 GNU make provides the features we need to do it without
2116 resorting to a script. Also, we've found that fastmaking is
2117 less useful since the advent of GHC's recompilation checker (see
2118 the User's Guide section on "Separate Compilation").</para>
2122 <sect1 id="sec-makefile-arch">
2123 <title>The <filename>Makefile</filename> architecture</title>
2124 <indexterm><primary>makefile architecture</primary></indexterm>
2126 <para><command>make</command> is great if everything
2127 works—you type <command>gmake install</command> and lo! the
2128 right things get compiled and installed in the right places. Our
2129 goal is to make this happen often, but somehow it often doesn't;
2130 instead some weird error message eventually emerges from the
2131 bowels of a directory you didn't know existed.</para>
2133 <para>The purpose of this section is to give you a road-map to
2134 help you figure out what is going right and what is going
2138 <title>Debugging</title>
2140 <para>Debugging <filename>Makefile</filename>s is something of a
2141 black art, but here's a couple of tricks that we find
2142 particularly useful. The following command allows you to see
2143 the contents of any make variable in the context of the current
2144 <filename>Makefile</filename>:</para>
2146 <screen>$ make show VALUE=HS_SRCS</screen>
2148 <para>where you can replace <literal>HS_SRCS</literal> with the
2149 name of any variable you wish to see the value of.</para>
2151 <para>GNU make has a <option>-d</option> option which generates
2152 a dump of the decision procedure used to arrive at a conclusion
2153 about which files should be recompiled. Sometimes useful for
2154 tracking down problems with superfluous or missing
2155 recompilations.</para>
2159 <title>A small project</title>
2161 <para>To get started, let us look at the
2162 <filename>Makefile</filename> for an imaginary small
2163 <literal>fptools</literal> project, <literal>small</literal>.
2164 Each project in <literal>fptools</literal> has its own directory
2165 in <constant>FPTOOLS_TOP</constant>, so the
2166 <literal>small</literal> project will have its own directory
2167 <constant>FPOOLS_TOP/small/</constant>. Inside the
2168 <filename>small/</filename> directory there will be a
2169 <filename>Makefile</filename>, looking something like
2172 <indexterm><primary>Makefile, minimal</primary></indexterm>
2175 # Makefile for fptools project "small"
2178 include $(TOP)/mk/boilerplate.mk
2180 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2183 include $(TOP)/target.mk
2186 <para>this <filename>Makefile</filename> has three
2191 <para>The first section includes
2194 One of the most important
2195 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2196 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
2201 a file of “boilerplate” code from the level
2202 above (which in this case will be
2203 <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2204 As its name suggests, <filename>boilerplate.mk</filename>
2205 consists of a large quantity of standard
2206 <filename>Makefile</filename> code. We discuss this
2207 boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
2208 <indexterm><primary>include, directive in
2209 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2210 inclusion</primary></indexterm></para>
2212 <para>Before the <literal>include</literal> statement, you
2213 must define the <command>make</command> variable
2214 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2215 to be the directory containing the <filename>mk</filename>
2216 directory in which the <filename>boilerplate.mk</filename>
2217 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2220 include ../mk/boilerplate.mk # NO NO NO
2224 <para>Why? Because the <filename>boilerplate.mk</filename>
2225 file needs to know where it is, so that it can, in turn,
2226 <literal>include</literal> other files. (Unfortunately,
2227 when an <literal>include</literal>d file does an
2228 <literal>include</literal>, the filename is treated relative
2229 to the directory in which <command>gmake</command> is being
2230 run, not the directory in which the
2231 <literal>include</literal>d sits.) In general,
2232 <emphasis>every file <filename>foo.mk</filename> assumes
2234 <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
2235 refers to itself.</emphasis> It is up to the
2236 <filename>Makefile</filename> doing the
2237 <literal>include</literal> to ensure this is the case.</para>
2239 <para>Files intended for inclusion in other
2240 <filename>Makefile</filename>s are written to have the
2241 following property: <emphasis>after
2242 <filename>foo.mk</filename> is <literal>include</literal>d,
2243 it leaves <constant>TOP</constant> containing the same value
2244 as it had just before the <literal>include</literal>
2245 statement</emphasis>. In our example, this invariant
2246 guarantees that the <literal>include</literal> for
2247 <filename>target.mk</filename> will look in the same
2248 directory as that for <filename>boilerplate.mk</filename>.</para>
2252 <para> The second section defines the following standard
2253 <command>make</command> variables:
2254 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2255 (the source files from which is to be built), and
2256 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
2257 (the executable binary to be built). We will discuss in
2258 more detail what the “standard variables” are,
2259 and how they affect what happens, in <XRef
2260 LinkEnd="sec-targets">.</para>
2262 <para>The definition for <constant>SRCS</constant> uses the
2263 useful GNU <command>make</command> construct
2264 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2265 which expands to a list of all the files matching the
2266 pattern <literal>pat</literal> in the current directory. In
2267 this example, <constant>SRCS</constant> is set to the list
2268 of all the <filename>.lhs</filename> and
2269 <filename>.c</filename> files in the directory. (Let's
2270 suppose there is one of each, <filename>Foo.lhs</filename>
2271 and <filename>Baz.c</filename>.)</para>
2275 <para>The last section includes a second file of standard
2277 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2278 It contains the rules that tell <command>gmake</command> how
2279 to make the standard targets (<Xref
2280 LinkEnd="sec-standard-targets">). Why, you ask, can't this
2281 standard code be part of
2282 <filename>boilerplate.mk</filename>? Good question. We
2283 discuss the reason later, in <Xref
2284 LinkEnd="sec-boiler-arch">.</para>
2286 <para>You do not <emphasis>have</emphasis> to
2287 <literal>include</literal> the
2288 <filename>target.mk</filename> file. Instead, you can write
2289 rules of your own for all the standard targets. Usually,
2290 though, you will find quite a big payoff from using the
2291 canned rules in <filename>target.mk</filename>; the price
2292 tag is that you have to understand what canned rules get
2293 enabled, and what they do (<Xref
2294 LinkEnd="sec-targets">).</para>
2298 <para>In our example <filename>Makefile</filename>, most of the
2299 work is done by the two <literal>include</literal>d files. When
2300 you say <command>gmake all</command>, the following things
2305 <para><command>gmake</command> figures out that the object
2306 files are <filename>Foo.o</filename> and
2307 <filename>Baz.o</filename>.</para>
2311 <para>It uses a boilerplate pattern rule to compile
2312 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2313 using a Haskell compiler. (Which one? That is set in the
2314 build configuration.)</para>
2318 <para>It uses another standard pattern rule to compile
2319 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2320 using a C compiler. (Ditto.)</para>
2324 <para>It links the resulting <filename>.o</filename> files
2325 together to make <literal>small</literal>, using the Haskell
2326 compiler to do the link step. (Why not use
2327 <command>ld</command>? Because the Haskell compiler knows
2328 what standard libraries to link in. How did
2329 <command>gmake</command> know to use the Haskell compiler to
2330 do the link, rather than the C compiler? Because we set the
2331 variable <constant>HS_PROG</constant> rather than
2332 <constant>C_PROG</constant>.)</para>
2336 <para>All <filename>Makefile</filename>s should follow the above
2337 three-section format.</para>
2341 <title>A larger project</title>
2343 <para>Larger projects are usually structured into a number of
2344 sub-directories, each of which has its own
2345 <filename>Makefile</filename>. (In very large projects, this
2346 sub-structure might be iterated recursively, though that is
2347 rare.) To give you the idea, here's part of the directory
2348 structure for the (rather large) GHC project:</para>
2358 ...source files for documentation...
2361 ...source files for driver...
2364 parser/...source files for parser...
2365 renamer/...source files for renamer...
2369 <para>The sub-directories <filename>docs</filename>,
2370 <filename>driver</filename>, <filename>compiler</filename>, and
2371 so on, each contains a sub-component of GHC, and each has its
2372 own <filename>Makefile</filename>. There must also be a
2373 <filename>Makefile</filename> in
2374 <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
2375 It does most of its work by recursively invoking
2376 <command>gmake</command> on the <filename>Makefile</filename>s
2377 in the sub-directories. We say that
2378 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2379 <filename>Makefile</filename></emphasis>, because it does little
2380 except organise its children, while the
2381 <filename>Makefile</filename>s in the sub-directories are all
2382 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2383 principle the sub-directories might themselves contain a
2384 non-leaf <filename>Makefile</filename> and several
2385 sub-sub-directories, but that does not happen in GHC.)</para>
2387 <para>The <filename>Makefile</filename> in
2388 <filename>ghc/compiler</filename> is considered a leaf
2389 <filename>Makefile</filename> even though the
2390 <filename>ghc/compiler</filename> has sub-directories, because
2391 these sub-directories do not themselves have
2392 <filename>Makefile</filename>s in them. They are just used to
2393 structure the collection of modules that make up GHC, but all
2394 are managed by the single <filename>Makefile</filename> in
2395 <filename>ghc/compiler</filename>.</para>
2397 <para>You will notice that <filename>ghc/</filename> also
2398 contains a directory <filename>ghc/mk/</filename>. It contains
2399 GHC-specific <filename>Makefile</filename> boilerplate code.
2400 More precisely:</para>
2404 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2405 at the top of <filename>ghc/Makefile</filename>, and of all
2406 the leaf <filename>Makefile</filename>s in the
2407 sub-directories. It in turn <literal>include</literal>s the
2408 main boilerplate file
2409 <filename>mk/boilerplate.mk</filename>.</para>
2413 <para><filename>ghc/mk/target.mk</filename> is
2414 <literal>include</literal>d at the bottom of
2415 <filename>ghc/Makefile</filename>, and of all the leaf
2416 <filename>Makefile</filename>s in the sub-directories. It
2417 in turn <literal>include</literal>s the file
2418 <filename>mk/target.mk</filename>.</para>
2422 <para>So these two files are the place to look for GHC-wide
2423 customisation of the standard boilerplate.</para>
2426 <sect2 id="sec-boiler-arch">
2427 <title>Boilerplate architecture</title>
2428 <indexterm><primary>boilerplate architecture</primary></indexterm>
2430 <para>Every <filename>Makefile</filename> includes a
2431 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2432 file at the top, and
2433 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2434 file at the bottom. In this section we discuss what is in these
2435 files, and why there have to be two of them. In general:</para>
2439 <para><filename>boilerplate.mk</filename> consists of:</para>
2443 <para><emphasis>Definitions of millions of
2444 <command>make</command> variables</emphasis> that
2445 collectively specify the build configuration. Examples:
2446 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2447 the options to feed to the Haskell compiler;
2448 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2449 the sub-directories to enable within the
2450 <literal>nofib</literal> project;
2451 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2452 the name of the Haskell compiler to use when compiling
2453 GHC in the <literal>ghc</literal> project.</para>
2457 <para><emphasis>Standard pattern rules</emphasis> that
2458 tell <command>gmake</command> how to construct one file
2459 from another.</para>
2463 <para><filename>boilerplate.mk</filename> needs to be
2464 <literal>include</literal>d at the <emphasis>top</emphasis>
2465 of each <filename>Makefile</filename>, so that the user can
2466 replace the boilerplate definitions or pattern rules by
2467 simply giving a new definition or pattern rule in the
2468 <filename>Makefile</filename>. <command>gmake</command>
2469 simply takes the last definition as the definitive one.</para>
2471 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2472 definitions, it is also quite common to
2473 <emphasis>augment</emphasis> them. For example, a
2474 <filename>Makefile</filename> might say:</para>
2480 <para>thereby adding “<option>-O</option>” to
2482 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
2486 <para><filename>target.mk</filename> contains
2487 <command>make</command> rules for the standard targets
2488 described in <Xref LinkEnd="sec-standard-targets">. These
2489 rules are selectively included, depending on the setting of
2490 certain <command>make</command> variables. These variables
2491 are usually set in the middle section of the
2492 <filename>Makefile</filename> between the two
2493 <literal>include</literal>s.</para>
2495 <para><filename>target.mk</filename> must be included at the
2496 end (rather than being part of
2497 <filename>boilerplate.mk</filename>) for several tiresome
2503 <para><command>gmake</command> commits target and
2504 dependency lists earlier than it should. For example,
2505 <FIlename>target.mk</FIlename> has a rule that looks
2509 $(HS_PROG) : $(OBJS)
2510 $(HC) $(LD_OPTS) $< -o $@
2513 <para>If this rule was in
2514 <filename>boilerplate.mk</filename> then
2515 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
2517 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2518 would not have their final values at the moment
2519 <command>gmake</command> encountered the rule. Alas,
2520 <command>gmake</command> takes a snapshot of their
2521 current values, and wires that snapshot into the rule.
2522 (In contrast, the commands executed when the rule
2523 “fires” are only substituted at the moment
2524 of firing.) So, the rule must follow the definitions
2525 given in the <filename>Makefile</filename> itself.</para>
2529 <para>Unlike pattern rules, ordinary rules cannot be
2530 overriden or replaced by subsequent rules for the same
2531 target (at least, not without an error message).
2532 Including ordinary rules in
2533 <filename>boilerplate.mk</filename> would prevent the
2534 user from writing rules for specific targets in specific
2539 <para>There are a couple of other reasons I've
2540 forgotten, but it doesn't matter too much.</para>
2547 <sect2 id="sec-boiler">
2548 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2549 <indexterm><primary>boilerplate.mk</primary></indexterm>
2551 <para>If you look at
2552 <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
2553 you will find that it consists of the following sections, each
2554 held in a separate file:</para>
2558 <term><filename>config.mk</filename></term>
2559 <indexterm><primary>config.mk</primary></indexterm>
2561 <para>is the build configuration file we discussed at
2562 length in <Xref LinkEnd="sec-build-config">.</para>
2567 <term><filename>paths.mk</filename></term>
2568 <indexterm><primary>paths.mk</primary></indexterm>
2570 <para>defines <command>make</command> variables for
2571 pathnames and file lists. This file contains code for
2572 automatically compiling lists of source files and deriving
2573 lists of object files from those. The results can be
2574 overriden in the <filename>Makefile</filename>, but in
2575 most cases the automatic setup should do the right
2578 <para>The following variables may be set in the
2579 <filename>Makefile</filename> to affect how the automatic
2580 source file search is done:</para>
2584 <term><literal>ALL_DIRS</literal></term>
2585 <indexterm><primary><literal>ALL_DIRS</literal></primary>
2588 <para>Set to a list of directories to search in
2589 addition to the current directory for source
2595 <term><literal>EXCLUDE_SRCS</literal></term>
2596 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2599 <para>Set to a list of source files (relative to the
2600 current directory) to omit from the automatic
2601 search. The source searching machinery is clever
2602 enough to know that if you exclude a source file
2603 from which other sources are derived, then the
2604 derived sources should also be excluded. For
2605 example, if you set <literal>EXCLUDED_SRCS</literal>
2606 to include <filename>Foo.y</filename>, then
2607 <filename>Foo.hs</filename> will also be
2613 <term><literal>EXTRA_SRCS</literal></term>
2614 <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
2617 <para>Set to a list of extra source files (perhaps
2618 in directories not listed in
2619 <literal>ALL_DIRS</literal>) that should be
2625 <para>The results of the automatic source file search are
2626 placed in the following make variables:</para>
2630 <term><literal>SRCS</literal></term>
2631 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2633 <para>All source files found, sorted and without
2634 duplicates, including those which might not exist
2635 yet but will be derived from other existing sources.
2636 <literal>SRCS</literal> <emphasis>can</emphasis> be
2637 overriden if necessary, in which case the variables
2638 below will follow suit.</para>
2643 <term><literal>HS_SRCS</literal></term>
2644 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2646 <para>all Haskell source files in the current
2647 directory, including those derived from other source
2648 files (eg. Happy sources also give rise to Haskell
2654 <term><literal>HS_OBJS</literal></term>
2655 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2657 <para>Object files derived from
2658 <literal>HS_SRCS</literal>.</para>
2663 <term><literal>HS_IFACES</literal></term>
2664 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2666 <para>Interface files (<literal>.hi</literal> files)
2667 derived from <literal>HS_SRCS</literal>.</para>
2672 <term><literal>C_SRCS</literal></term>
2673 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2675 <para>All C source files found.</para>
2680 <term><literal>C_OBJS</literal></term>
2681 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2683 <para>Object files derived from
2684 <literal>C_SRCS</literal>.</para>
2689 <term><literal>SCRIPT_SRCS</literal></term>
2690 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2692 <para>All script source files found
2693 (<literal>.lprl</literal> files).</para>
2698 <term><literal>SCRIPT_OBJS</literal></term>
2699 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2701 <para><quote>object</quote> files derived from
2702 <literal>SCRIPT_SRCS</literal>
2703 (<literal>.prl</literal> files).</para>
2708 <term><literal>HSC_SRCS</literal></term>
2709 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2711 <para>All <literal>hsc2hs</literal> source files
2712 (<literal>.hsc</literal> files).</para>
2717 <term><literal>HAPPY_SRCS</literal></term>
2718 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2720 <para>All <literal>happy</literal> source files
2721 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2726 <term><literal>OBJS</literal></term>
2727 <indexterm><primary>OBJS</primary></indexterm>
2729 <para>the concatenation of
2730 <literal>$(HS_OBJS)</literal>,
2731 <literal>$(C_OBJS)</literal>, and
2732 <literal>$(SCRIPT_OBJS)</literal>.</para>
2737 <para>Any or all of these definitions can easily be
2738 overriden by giving new definitions in your
2739 <filename>Makefile</filename>.</para>
2741 <para>What, exactly, does <filename>paths.mk</filename>
2742 consider a <quote>source file</quote> to be? It's based
2743 on the file's suffix (e.g. <filename>.hs</filename>,
2744 <filename>.lhs</filename>, <filename>.c</filename>,
2745 <filename>.hy</filename>, etc), but this is the kind of
2746 detail that changes, so rather than enumerate the source
2747 suffices here the best thing to do is to look in
2748 <filename>paths.mk</filename>.</para>
2753 <term><filename>opts.mk</filename></term>
2754 <indexterm><primary>opts.mk</primary></indexterm>
2756 <para>defines <command>make</command> variables for option
2757 strings to pass to each program. For example, it defines
2758 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
2759 the option strings to pass to the Haskell compiler. See
2760 <Xref LinkEnd="sec-suffix">.</para>
2765 <term><filename>suffix.mk</filename></term>
2766 <indexterm><primary>suffix.mk</primary></indexterm>
2768 <para>defines standard pattern rules—see <Xref
2769 LinkEnd="sec-suffix">.</para>
2774 <para>Any of the variables and pattern rules defined by the
2775 boilerplate file can easily be overridden in any particular
2776 <filename>Makefile</filename>, because the boilerplate
2777 <literal>include</literal> comes first. Definitions after this
2778 <literal>include</literal> directive simply override the default
2779 ones in <filename>boilerplate.mk</filename>.</para>
2782 <sect2 id="sec-suffix">
2783 <title>Pattern rules and options</title>
2784 <indexterm><primary>Pattern rules</primary></indexterm>
2787 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
2788 defines standard <emphasis>pattern rules</emphasis> that say how
2789 to build one kind of file from another, for example, how to
2790 build a <filename>.o</filename> file from a
2791 <filename>.c</filename> file. (GNU <command>make</command>'s
2792 <emphasis>pattern rules</emphasis> are more powerful and easier
2793 to use than Unix <command>make</command>'s <emphasis>suffix
2794 rules</emphasis>.)</para>
2796 <para>Almost all the rules look something like this:</para>
2801 $(CC) $(CC_OPTS) -c $< -o $@
2804 <para>Here's how to understand the rule. It says that
2805 <emphasis>something</emphasis><filename>.o</filename> (say
2806 <filename>Foo.o</filename>) can be built from
2807 <emphasis>something</emphasis><filename>.c</filename>
2808 (<filename>Foo.c</filename>), by invoking the C compiler (path
2809 name held in <constant>$(CC)</constant>), passing to it
2810 the options <constant>$(CC_OPTS)</constant> and
2811 the rule's dependent file of the rule
2812 <literal>$<</literal> (<filename>Foo.c</filename> in
2813 this case), and putting the result in the rule's target
2814 <literal>$@</literal> (<filename>Foo.o</filename> in this
2817 <para>Every program is held in a <command>make</command>
2818 variable defined in <filename>mk/config.mk</filename>—look
2819 in <filename>mk/config.mk</filename> for the complete list. One
2820 important one is the Haskell compiler, which is called
2821 <constant>$(HC)</constant>.</para>
2823 <para>Every program's options are are held in a
2824 <command>make</command> variables called
2825 <constant><prog>_OPTS</constant>. the
2826 <constant><prog>_OPTS</constant> variables are
2827 defined in <filename>mk/opts.mk</filename>. Almost all of them
2828 are defined like this:</para>
2831 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
2834 <para>The four variables from which
2835 <constant>CC_OPTS</constant> is built have the following
2840 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
2842 <para>options passed to all C compilations.</para>
2847 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
2849 <para>options passed to C compilations for way
2850 <literal><way></literal>. For example,
2851 <constant>WAY_mp_CC_OPTS</constant>
2852 gives options to pass to the C compiler when compiling way
2853 <literal>mp</literal>. The variable
2854 <constant>WAY_CC_OPTS</constant> holds
2855 options to pass to the C compiler when compiling the
2856 standard way. (<Xref LinkEnd="sec-ways"> dicusses
2857 multi-way compilation.)</para>
2862 <term><constant><module>_CC_OPTS</constant>:</term>
2864 <para>options to pass to the C compiler that are specific
2865 to module <literal><module></literal>. For example,
2866 <constant>SMap_CC_OPTS</constant> gives the
2867 specific options to pass to the C compiler when compiling
2868 <filename>SMap.c</filename>.</para>
2873 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
2875 <para>extra options to pass to all C compilations. This
2876 is intended for command line use, thus:</para>
2879 gmake libHS.a EXTRA_CC_OPTS="-v"
2886 <sect2 id="sec-targets">
2887 <title>The main <filename>mk/target.mk</filename> file</title>
2888 <indexterm><primary>target.mk</primary></indexterm>
2890 <para><filename>target.mk</filename> contains canned rules for
2891 all the standard targets described in <Xref
2892 LinkEnd="sec-standard-targets">. It is complicated by the fact
2893 that you don't want all of these rules to be active in every
2894 <filename>Makefile</filename>. Rather than have a plethora of
2895 tiny files which you can include selectively, there is a single
2896 file, <filename>target.mk</filename>, which selectively includes
2897 rules based on whether you have defined certain variables in
2898 your <filename>Makefile</filename>. This section explains what
2899 rules you get, what variables control them, and what the rules
2900 do. Hopefully, you will also get enough of an idea of what is
2901 supposed to happen that you can read and understand any weird
2902 special cases yourself.</para>
2906 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
2908 <para>If <constant>HS_PROG</constant> is defined,
2909 you get rules with the following targets:</para>
2913 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
2915 <para>itself. This rule links
2916 <constant>$(OBJS)</constant> with the Haskell
2917 runtime system to get an executable called
2918 <constant>$(HS_PROG)</constant>.</para>
2923 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
2926 <constant>$(HS_PROG)</constant> in
2927 <constant>$(bindir)</constant>.</para>
2936 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
2938 <para>is similar to <constant>HS_PROG</constant>,
2939 except that the link step links
2940 <constant>$(C_OBJS)</constant> with the C
2941 runtime system.</para>
2946 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
2948 <para>is similar to <constant>HS_PROG</constant>,
2949 except that it links
2950 <constant>$(LIB_OBJS)</constant> to make the
2951 library archive <constant>$(LIBRARY)</constant>,
2952 and <literal>install</literal> installs it in
2953 <constant>$(libdir)</constant>.</para>
2958 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
2960 <para>…</para>
2965 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
2967 <para>…</para>
2972 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
2974 <para>If <constant>HS_SRCS</constant> is defined
2975 and non-empty, a rule for the target
2976 <literal>depend</literal> is included, which generates
2977 dependency information for Haskell programs. Similarly
2978 for <constant>C_SRCS</constant>.</para>
2983 <para>All of these rules are “double-colon” rules,
2987 install :: $(HS_PROG)
2988 ...how to install it...
2991 <para>GNU <command>make</command> treats double-colon rules as
2992 separate entities. If there are several double-colon rules for
2993 the same target it takes each in turn and fires it if its
2994 dependencies say to do so. This means that you can, for
2995 example, define both <constant>HS_PROG</constant> and
2996 <constant>LIBRARY</constant>, which will generate two rules for
2997 <literal>install</literal>. When you type <command>gmake
2998 install</command> both rules will be fired, and both the program
2999 and the library will be installed, just as you wanted.</para>
3002 <sect2 id="sec-subdirs">
3003 <title>Recursion</title>
3004 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3005 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3007 <para>In leaf <filename>Makefile</filename>s the variable
3008 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3009 is undefined. In non-leaf <filename>Makefile</filename>s,
3010 <constant>SUBDIRS</constant> is set to the list of
3011 sub-directories that contain subordinate
3012 <filename>Makefile</filename>s. <emphasis>It is up to you to
3013 set <constant>SUBDIRS</constant> in the
3014 <filename>Makefile</filename>.</emphasis> There is no automation
3015 here—<constant>SUBDIRS</constant> is too important to
3018 <para>When <constant>SUBDIRS</constant> is defined,
3019 <filename>target.mk</filename> includes a rather neat rule for
3020 the standard targets (<Xref LinkEnd="sec-standard-targets"> that
3021 simply invokes <command>make</command> recursively in each of
3022 the sub-directories.</para>
3024 <para><emphasis>These recursive invocations are guaranteed to
3025 occur in the order in which the list of directories is specified
3026 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3027 be important. For example, when you say <command>gmake
3028 boot</command> it can be important that the recursive invocation
3029 of <command>make boot</command> is done in one sub-directory
3030 (the include files, say) before another (the source files).
3031 Generally, put the most independent sub-directory first, and the
3032 most dependent last.</para>
3035 <sect2 id="sec-ways">
3036 <title>Way management</title>
3037 <indexterm><primary>way management</primary></indexterm>
3039 <para>We sometimes want to build essentially the same system in
3040 several different “ways”. For example, we want to build GHC's
3041 <literal>Prelude</literal> libraries with and without profiling,
3042 so that there is an appropriately-built library archive to link
3043 with when the user compiles his program. It would be possible
3044 to have a completely separate build tree for each such “way”,
3045 but it would be horribly bureaucratic, especially since often
3046 only parts of the build tree need to be constructed in multiple
3050 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3051 contains some clever magic to allow you to build several
3052 versions of a system; and to control locally how many versions
3053 are built and how they differ. This section explains the
3056 <para>The files for a particular way are distinguished by
3057 munging the suffix. The <quote>normal way</quote> is always
3058 built, and its files have the standard suffices
3059 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3060 In addition, you can build one or more extra ways, each
3061 distinguished by a <emphasis>way tag</emphasis>. The object
3062 files and interface files for one of these extra ways are
3063 distinguished by their suffix. For example, way
3064 <literal>mp</literal> has files
3065 <filename>.mp_o</filename> and
3066 <filename>.mp_hi</filename>. Library archives have their
3067 way tag the other side of the dot, for boring reasons; thus,
3068 <filename>libHS_mp.a</filename>.</para>
3070 <para>A <command>make</command> variable called
3071 <constant>way</constant> holds the current way tag.
3072 <emphasis><constant>way</constant> is only ever set on the
3073 command line of <command>gmake</command></emphasis> (usually in
3074 a recursive invocation of <command>gmake</command> by the
3075 system). It is never set inside a
3076 <filename>Makefile</filename>. So it is a global constant for
3077 any one invocation of <command>gmake</command>. Two other
3078 <command>make</command> variables,
3079 <constant>way_</constant> and
3080 <constant>_way</constant> are immediately derived from
3081 <constant>$(way)</constant> and never altered. If
3082 <constant>way</constant> is not set, then neither are
3083 <constant>way_</constant> and
3084 <constant>_way</constant>, and the invocation of
3085 <command>make</command> will build the <quote>normal
3086 way</quote>. If <constant>way</constant> is set, then the other
3087 two variables are set in sympathy. For example, if
3088 <constant>$(way)</constant> is “<literal>mp</literal>”,
3089 then <constant>way_</constant> is set to
3090 “<literal>mp_</literal>” and
3091 <constant>_way</constant> is set to
3092 “<literal>_mp</literal>”. These three variables are
3093 then used when constructing file names.</para>
3095 <para>So how does <command>make</command> ever get recursively
3096 invoked with <constant>way</constant> set? There are two ways
3097 in which this happens:</para>
3101 <para>For some (but not all) of the standard targets, when
3102 in a leaf sub-directory, <command>make</command> is
3103 recursively invoked for each way tag in
3104 <constant>$(WAYS)</constant>. You set
3105 <constant>WAYS</constant> in the
3106 <filename>Makefile</filename> to the list of way tags you
3107 want these targets built for. The mechanism here is very
3108 much like the recursive invocation of
3109 <command>make</command> in sub-directories (<Xref
3110 LinkEnd="sec-subdirs">). It is up to you to set
3111 <constant>WAYS</constant> in your
3112 <filename>Makefile</filename>; this is how you control what
3113 ways will get built.</para>
3117 <para>For a useful collection of targets (such as
3118 <filename>libHS_mp.a</filename>,
3119 <filename>Foo.mp_o</filename>) there is a rule which
3120 recursively invokes <command>make</command> to make the
3121 specified target, setting the <constant>way</constant>
3122 variable. So if you say <command>gmake
3123 Foo.mp_o</command> you should see a recursive
3124 invocation <command>gmake Foo.mp_o way=mp</command>,
3125 and <emphasis>in this recursive invocation the pattern rule
3126 for compiling a Haskell file into a <filename>.o</filename>
3127 file will match</emphasis>. The key pattern rules (in
3128 <filename>suffix.mk</filename>) look like this:
3132 $(HC) $(HC_OPTS) $< -o $@
3139 <para>You can invoke <command>make</command> with a
3140 particular <literal>way</literal> setting yourself, in order
3141 to build files related to a particular
3142 <literal>way</literal> in the current directory. eg.
3148 will build files for the profiling way only in the current
3155 <title>When the canned rule isn't right</title>
3157 <para>Sometimes the canned rule just doesn't do the right thing.
3158 For example, in the <literal>nofib</literal> suite we want the
3159 link step to print out timing information. The thing to do here
3160 is <emphasis>not</emphasis> to define
3161 <constant>HS_PROG</constant> or
3162 <constant>C_PROG</constant>, and instead define a special
3163 purpose rule in your own <filename>Makefile</filename>. By
3164 using different variable names you will avoid the canned rules
3165 being included, and conflicting with yours.</para>
3169 <sect1 id="building-docs">
3170 <title>Building the documentation</title>
3172 <sect2 id="pre-supposed-doc-tools">
3173 <title>Tools for building the Documentation</title>
3175 <para>The following additional tools are required if you want to
3176 format the documentation that comes with the
3177 <literal>fptools</literal> projects:</para>
3181 <term>DocBook</term>
3182 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3183 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3185 <para>Much of our documentation is written in SGML, using
3186 the DocBook DTD. Instructions on installing and
3187 configuring the DocBook tools are below.</para>
3193 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3194 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3196 <para>A decent TeX distribution is required if you want to
3197 produce printable documentation. We recomment teTeX,
3198 which includes just about everything you need.</para>
3203 <term>Haddock</term>
3204 <indexterm><primary>Haddock</primary>
3207 <para>Haddock is a Haskell documentation tool that we use
3208 for automatically generating documentation from the
3209 library source code. It is an <literal>fptools</literal>
3210 project in itself. To build documentation for the
3211 libraries (<literal>fptools/libraries</literal>) you
3212 should check out and build Haddock in
3213 <literal>fptools/haddock</literal>. Haddock requires GHC
3221 <title>Installing the DocBook tools</title>
3224 <title>Installing the DocBook tools on Linux</title>
3226 <para>If you're on a recent RedHat system (7.0+), you probably
3227 have working DocBook tools already installed. The configure
3228 script should detect your setup and you're away.</para>
3230 <para>If you don't have DocBook tools installed, and you are
3231 using a system that can handle RedHat RPM packages, you can
3232 probably use the <ULink
3233 URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
3234 DocBook tools</ULink>, which is the most shrink-wrapped SGML
3235 suite that we could find. You need all the RPMs except for
3236 psgml (i.e. <Filename>docbook</Filename>,
3237 <Filename>jade</Filename>, <Filename>jadetex</Filename>,
3238 <Filename>sgmlcommon</Filename> and
3239 <Filename>stylesheets</Filename>). Note that most of these
3240 RPMs are architecture neutral, so are likely to be found in a
3241 <Filename>noarch</Filename> directory. The SuSE RPMs also
3242 work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
3243 (7.0 and later should be OK), but they are easy to fix: just
3245 <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
3246 to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
3250 <title>Installing DocBook on FreeBSD</title>
3252 <para>On FreeBSD systems, the easiest way to get DocBook up
3253 and running is to install it from the ports tree or a
3254 pre-compiled package (packages are available from your local
3255 FreeBSD mirror site).</para>
3257 <para>To use the ports tree, do this:
3259 $ cd /usr/ports/textproc/docproj
3262 This installs the FreeBSD documentation project tools, which
3263 includes everything needed to format the GHC
3264 documentation.</para>
3268 <title>Installing from binaries on Windows</title>
3270 <Para>It's a good idea to use Norman Walsh's <ULink
3271 URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
3272 notes</ULink> as a guide. You should get version 3.1 of
3273 DocBook, and note that his file <Filename>test.sgm</Filename>
3274 won't work, as it needs version 3.0. You should unpack Jade
3275 into <Filename>\Jade</Filename>, along with the entities,
3276 DocBook into <Filename>\docbook</Filename>, and the DocBook
3277 stylesheets into <Filename>\docbook\stylesheets</Filename> (so
3278 they actually end up in
3279 <Filename>\docbook\stylesheets\docbook</Filename>).</para>
3284 <title>Installing the DocBook tools from source</title>
3289 <para>Install <ULink
3290 URL="http://openjade.sourceforge.net/">OpenJade</ULink>
3291 (Windows binaries are available as well as sources). If you
3292 want DVI, PS, or PDF then install JadeTeX from the
3293 <Filename>dsssl</Filename> subdirectory. (If you get the
3297 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
3300 your version of <Command>hyperref</Command> is out of date;
3301 download it from CTAN
3302 (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
3303 and make it, ensuring that you have first removed or renamed
3304 your old copy. If you start getting file not found errors
3305 when making the test for <Command>hyperref</Command>, you
3306 can abort at that point and proceed straight to
3307 <Command>make install</Command>, or enter them as
3308 <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
3310 <para>Make links from <Filename>virtex</Filename> to
3311 <Filename>jadetex</Filename> and
3312 <Filename>pdfvirtex</Filename> to
3313 <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
3314 and PDF output will not work). Copy
3315 <Filename>dsssl/*.{dtd,dsl}</Filename> and
3316 <Filename>catalog</Filename> to
3317 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3321 <title>DocBook and the DocBook stylesheets</title>
3323 <para>Get a Zip of <ULink
3324 URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
3325 and install the contents in
3326 <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
3328 <para>Get the <ULink
3329 URL="http://nwalsh.com/docbook/dsssl/">DocBook
3330 stylesheets</ULink> and install in
3331 <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
3332 (thereby creating a subdirectory docbook). For indexing,
3333 copy or link <Filename>collateindex.pl</Filename> from the
3334 DocBook stylesheets archive in <Filename>bin</Filename> into
3335 a directory on your <Constant>PATH</Constant>.</para>
3337 <para>Download the <ULink
3338 URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
3339 entities</ULink> into
3340 <Filename>/usr/[local/]lib/sgml</Filename>.</para>
3346 <title>Configuring the DocBook tools</title>
3348 <Para>Once the DocBook tools are installed, the configure script
3349 will detect them and set up the build system accordingly. If you
3350 have a system that isn't supported, let us know, and we'll try
3355 <title>Remaining problems</title>
3357 <para>If you install from source, you'll get a pile of warnings
3360 <Screen>DTDDECL catalog entries are not supported</Screen>
3362 every time you build anything. These can safely be ignored, but
3363 if you find them tedious you can get rid of them by removing all
3364 the <Constant>DTDDECL</Constant> entries from
3365 <Filename>docbook.cat</Filename>.</para>
3369 <title>Building the documentation</title>
3371 <para>To build documentation in a certain format, you can
3372 say, for example,</para>
3378 <para>to build HTML documentation below the current directory.
3379 The available formats are: <literal>dvi</literal>,
3380 <literal>ps</literal>, <literal>pdf</literal>,
3381 <literal>html</literal>, and <literal>rtf</literal>. Note that
3382 not all documentation can be built in all of these formats: HTML
3383 documentation is generally supported everywhere, and DocBook
3384 documentation might support the other formats (depending on what
3385 other tools you have installed).</para>
3387 <para>All of these targets are recursive; that is, saying
3388 <literal>make html</literal> will make HTML docs for all the
3389 documents recursively below the current directory.</para>
3391 <para>Because there are many different formats that the DocBook
3392 documentation can be generated in, you have to select which ones
3393 you want by setting the <literal>SGMLDocWays</literal> variable
3394 to a list of them. For example, in
3395 <filename>build.mk</filename> you might have a line:</para>
3398 SGMLDocWays = html ps
3401 <para>This will cause the documentation to be built in the requested
3402 formats as part of the main build (the default is not to build
3403 any documentation at all).</para>
3407 <title>Installing the documentation</title>
3409 <para>To install the documentation, use:</para>
3415 <para>This will install the documentation into
3416 <literal>$(datadir)</literal> (which defaults to
3417 <literal>$(prefix)/share</literal>). The exception is HTML
3418 documentation, which goes into
3419 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3421 <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
3422 to a list of formats, the <literal>install-docs</literal> target
3423 won't do anything for SGML documentation.</para>
3429 <sect1 id="sec-porting-ghc">
3430 <title>Porting GHC</title>
3432 <para>This section describes how to port GHC to a currenly
3433 unsupported platform. There are two distinct
3434 possibilities:</para>
3438 <para>The hardware architecture for your system is already
3439 supported by GHC, but you're running an OS that isn't
3440 supported (or perhaps has been supported in the past, but
3441 currently isn't). This is the easiest type of porting job,
3442 but it still requires some careful bootstrapping. Proceed to
3443 <xref linkend="sec-booting-from-hc">.</para>
3447 <para>Your system's hardware architecture isn't supported by
3448 GHC. This will be a more difficult port (though by comparison
3449 perhaps not as difficult as porting gcc). Proceed to <xref
3450 linkend="unregisterised-porting">.</para>
3454 <sect2 id="sec-booting-from-hc">
3455 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3457 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3458 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3459 <indexterm><primary>porting GHC</primary></indexterm>
3461 <para>Bootstrapping GHC on a system without GHC already
3462 installed is achieved by taking the intermediate C files (known
3463 as HC files) from a GHC compilation on a supported system to the
3464 target machine, and compiling them using gcc to get a working
3467 <para><emphasis>NOTE: GHC version 5.xx is significantly harder
3468 to bootstrap from C than previous versions. We recommend
3469 starting from version 4.08.2 if you need to bootstrap in this
3470 way.</emphasis></para>
3472 <para>HC files are architecture-dependent (but not
3473 OS-dependent), so you have to get a set that were generated on
3474 similar hardware. There may be some supplied on the GHC
3475 download page, otherwise you'll have to compile some up
3476 yourself, or start from <emphasis>unregisterised</emphasis> HC
3477 files - see <xref linkend="unregisterised-porting">.</para>
3479 <para>The following steps should result in a working GHC build
3480 with full libraries:</para>
3484 <para>Unpack the HC files on top of a fresh source tree
3485 (make sure the source tree version matches the version of
3486 the HC files <emphasis>exactly</emphasis>!). This will
3487 place matching <filename>.hc</filename> files next to the
3488 corresponding Haskell source (<filename>.hs</filename> or
3489 <filename>.lhs</filename>) in the compiler subdirectory
3490 <filename>ghc/compiler</filename> and in the libraries
3491 (subdirectories of <filename>hslibs</filename> and
3492 <literal>libraries</literal>).</para>
3496 <para>The actual build process is fully automated by the
3497 <filename>hc-build</filename> script located in the
3498 <filename>distrib</filename> directory. If you eventually
3499 want to install GHC into the directory
3500 <replaceable>dir</replaceable>, the following
3501 command will execute the whole build process (it won't
3502 install yet):</para>
3505 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
3507 <indexterm><primary>--hc-build</primary></indexterm>
3509 <para>By default, the installation directory is
3510 <filename>/usr/local</filename>. If that is what you want,
3511 you may omit the argument to <filename>hc-build</filename>.
3512 Generally, any option given to <filename>hc-build</filename>
3513 is passed through to the configuration script
3514 <filename>configure</filename>. If
3515 <filename>hc-build</filename> successfully completes the
3516 build process, you can install the resulting system, as
3526 <sect2 id="unregisterised-porting">
3527 <title>Porting GHC to a new architecture</title>
3529 <para>The first step in porting to a new architecture is to get
3530 an <firstterm>unregisterised</firstterm> build working. An
3531 unregisterised build is one that compiles via vanilla C only.
3532 By contrast, a registerised build uses the following
3533 architecture-specific hacks for speed:</para>
3537 <para>Global register variables: certain abstract machine
3538 <quote>registers</quote> are mapped to real machine
3539 registers, depending on how many machine registers are
3541 <filename>ghc/includes/MachRegs.h</filename>).</para>
3545 <para>Assembly-mangling: when compiling via C, we feed the
3546 assembly generated by gcc though a Perl script known as the
3547 <firstterm>mangler</firstterm> (see
3548 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3549 mangler rearranges the assembly to support tail-calls and
3550 various other optimisations.</para>
3554 <para>In an unregisterised build, neither of these hacks are
3555 used — the idea is that the C code generated by the
3556 compiler should compile using gcc only. The lack of these
3557 optimisations costs about a factor of two in performance, but
3558 since unregisterised compilation is usually just a step on the
3559 way to a full registerised port, we don't mind too much.</para>
3562 <title>Building an unregisterised port</title>
3564 <para>The first step is to get some unregisterised HC files.
3565 Either (a) download them from the GHC site (if there are
3566 some available for the right version of GHC), or
3567 (b) build them yourself on any machine with a working
3568 GHC. If at all possible this should be a machine with the
3569 same word size as the target.</para>
3571 <para>There is a script available which should automate the
3572 process of doing the 2-stage bootstrap necessary to get the
3573 unregisterised HC files - it's available in <ulink
3574 url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
3577 <para>Now take these unregisterised HC files to the target
3578 platform and bootstrap a compiler from them as per the
3579 instructions in <xref linkend="sec-booting-from-hc">. In
3580 <filename>build.mk</filename>, you need to tell the build
3581 system that the compiler you're building is
3582 (a) unregisterised itself, and (b) builds
3583 unregisterised binaries. This varies depending on the GHC
3584 version you're bootstraping:</para>
3587 # build.mk for GHC 4.08.x
3588 GhcWithRegisterised=NO
3592 # build.mk for GHC 5.xx
3593 GhcUnregisterised=YES
3596 <para>Version 5.xx only: use the option
3597 <option>--enable-hc-boot-unregisterised</option> instead of
3598 <option>--enable-hc-boot</option> when running
3599 <filename>./configure</filename>.</para>
3601 <para>The build may not go through cleanly. We've tried to
3602 stick to writing portable code in most parts of the compiler,
3603 so it should compile on any POSIXish system with gcc, but in
3604 our experience most systems differ from the standards in one
3605 way or another. Deal with any problems as they arise - if you
3606 get stuck, ask the experts on
3607 <email>glasgow-haskell-users@haskell.org</email>.</para>
3609 <para>Once you have the unregisterised compiler up and
3610 running, you can use it to start a registerised port. The
3611 following sections describe the various parts of the system
3612 that will need architecture-specific tweaks in order to get a
3613 registerised build going.</para>
3615 <para>Lots of useful information about the innards of GHC is
3616 available in the <ulink
3617 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3618 Commentary</ulink>, which might be helpful if you run into
3619 some code which needs tweaking for your system.</para>
3623 <title>Porting the RTS</title>
3625 <para>The following files need architecture-specific code for a
3626 registerised build:</para>
3630 <term><filename>ghc/includes/MachRegs.h</filename></term>
3631 <indexterm><primary><filename>MachRegs.h</filename></primary>
3634 <para>Defines the STG-register to machine-register
3635 mapping. You need to know your platform's C calling
3636 convention, and which registers are generally available
3637 for mapping to global register variables. There are
3638 plenty of useful comments in this file.</para>
3642 <term><filename>ghc/includes/TailCalls.h</filename></term>
3643 <indexterm><primary><filename>TailCalls.h</filename></primary>
3646 <para>Macros that cooperate with the mangler (see <xref
3647 linkend="sec-mangler">) to make proper tail-calls
3652 <term><filename>ghc/rts/Adjustor.c</filename></term>
3653 <indexterm><primary><filename>Adjustor.c</filename></primary>
3657 <literal>foreign import "wrapper"</literal>
3659 <literal>foreign export dynamic</literal>).
3660 Not essential for getting GHC bootstrapped, so this file
3661 can be deferred until later if necessary.</para>
3665 <term><filename>ghc/rts/StgCRun.c</filename></term>
3666 <indexterm><primary><filename>StgCRun.c</filename></primary>
3669 <para>The little assembly layer between the C world and
3670 the Haskell world. See the comments and code for the
3671 other architectures in this file for pointers.</para>
3675 <term><filename>ghc/rts/MBlock.h</filename></term>
3676 <term><filename>ghc/rts/MBlock.c</filename></term>
3677 <indexterm><primary><filename>MBlock.h</filename></primary>
3679 <indexterm><primary><filename>MBlock.c</filename></primary>
3682 <para>These files are really OS-specific rather than
3683 architecture-specific. In <filename>MBlock.h</filename>
3684 is specified the absolute location at which the RTS
3685 should try to allocate memory on your platform (try to
3686 find an area which doesn't conflict with code or dynamic
3687 libraries). In <filename>Mblock.c</filename> you might
3688 need to tweak the call to <literal>mmap()</literal> for
3695 <sect3 id="sec-mangler">
3696 <title>The mangler</title>
3698 <para>The mangler is an evil Perl-script that rearranges the
3699 assembly code output from gcc to do two main things:</para>
3703 <para>Remove function prologues and epilogues, and all
3704 movement of the C stack pointer. This is to support
3705 tail-calls: every code block in Haskell code ends in an
3706 explicit jump, so we don't want the C-stack overflowing
3707 while we're jumping around between code blocks.</para>
3710 <para>Move the <firstterm>info table</firstterm> for a
3711 closure next to the entry code for that closure. In
3712 unregisterised code, info tables contain a pointer to the
3713 entry code, but in registerised compilation we arrange
3714 that the info table is shoved right up against the entry
3715 code, and addressed backwards from the entry code pointer
3716 (this saves a word in the info table and an extra
3717 indirection when jumping to the closure entry
3722 <para>The mangler is abstracted to a certain extent over some
3723 architecture-specific things such as the particular assembler
3724 directives used to herald symbols. Take a look at the
3725 definitions for other architectures and use these as a
3726 starting point.</para>
3730 <title>The native code generator</title>
3732 <para>The native code generator isn't essential to getting a
3733 registerised build going, but it's a desirable thing to have
3734 because it can cut compilation times in half. The native code
3735 generator is described in some detail in the <ulink
3736 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3737 commentary</ulink>.</para>
3743 <para>To support GHCi, you need to port the dynamic linker
3744 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
3745 currently supports the ELF and PEi386 object file formats - if
3746 your platform uses one of these then you probably don't have
3747 to do anything except fiddle with the
3748 <literal>#ifdef</literal>s at the top of
3749 <filename>Linker.c</filename> to tell it about your OS.</para>
3751 <para>If your system uses a different object file format, then
3752 you have to write a linker — good luck!</para>
3758 <sect1 id="sec-build-pitfalls">
3759 <title>Known pitfalls in building Glasgow Haskell
3761 <indexterm><primary>problems, building</primary></indexterm>
3762 <indexterm><primary>pitfalls, in building</primary></indexterm>
3763 <indexterm><primary>building pitfalls</primary></indexterm></title>
3766 WARNINGS about pitfalls and known “problems”:
3775 One difficulty that comes up from time to time is running out of space
3776 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
3777 compensate for the vagaries of different sysadmin approaches to temp
3779 <indexterm><primary>tmp, running out of space in</primary></indexterm>
3781 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
3782 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
3785 The best way around it is to say
3788 export TMPDIR=<dir>
3791 in your <filename>build.mk</filename> file.
3792 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
3801 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
3802 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
3810 When compiling via C, you'll sometimes get “warning: assignment from
3811 incompatible pointer type” out of GCC. Harmless.
3818 Similarly, <command>ar</command>chiving warning messages like the following are not
3822 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
3823 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
3833 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
3834 get an “Out of heap space” error message. These can vary with the
3835 vagaries of different systems, it seems. The solution is simple:
3842 If you're compiling with GHC 4.00 or later, then the
3843 <emphasis>maximum</emphasis> heap size must have been reached. This
3844 is somewhat unlikely, since the maximum is set to 64M by default.
3845 Anyway, you can raise it with the
3846 <option>-optCrts-M<size></option> flag (add this flag to
3847 <constant><module>_HC_OPTS</constant>
3848 <command>make</command> variable in the appropriate
3849 <filename>Makefile</filename>).
3856 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
3865 and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
3866 <constant><module>_HC_OPTS</constant>.)
3868 Alternatively, just cut to the chase:
3872 % make EXTRA_HC_OPTS=-optCrts-M128M
3881 If you try to compile some Haskell, and you get errors from GCC about
3882 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
3883 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
3885 As <command>fixincludes</command> is now automagically run as part of GCC installation,
3886 this bug also suggests that you have an old GCC.
3894 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
3898 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
3899 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
3901 ? # or, on some machines: ar s $i
3906 We'd be interested to know if this is still necessary.
3914 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
3915 a bit from one Unix to another. One particular gotcha is macro calls
3920 SLIT("Hello, world")
3924 Some <command>cpp</command>s treat the comma inside the string as separating two macro
3925 arguments, so you get
3929 :731: macro `SLIT' used with too many (2) args
3933 Alas, <command>cpp</command> doesn't tell you the offending file!
3935 Workaround: don't put weird things in string args to <command>cpp</command> macros.
3946 <Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
3949 This section summarises how to get the utilities you need on your
3950 Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
3951 installing and running GHC may be found in the user guide. In general,
3952 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
3953 You should read the GHC installation guide sections on Windows (in the user
3954 guide) before continuing to read these notes.
3958 <sect2><Title>Cygwin and MinGW</Title>
3960 <para> The Windows situation for building GHC is rather confusing. This section
3961 tries to clarify, and to establish terminology.</para>
3963 <sect3 id="ghc-mingw"><title>GHC-mingw</title>
3965 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
3966 is a collection of header
3967 files and import libraries that allow one to use <command>gcc</command> and produce
3968 native Win32 programs that do not rely on any third-party DLLs. The
3969 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
3970 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
3973 <para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
3974 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
3975 GHC compiles Haskell to C (or to
3976 assembly code), and then invokes these MinGW tools to generate an executable binary.
3977 The resulting binaries can run on any Win32 system.
3979 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
3981 <para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
3982 Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
3983 library; they have to do
3984 their input output using standard Haskell I/O libraries, or native Win32 bindings.
3988 <sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
3990 <para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
3991 <ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
3992 Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
3993 <command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
3994 A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
3996 <para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
3997 Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
3998 A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
3999 If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
4000 that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
4001 Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
4002 does not change, but the implementation certainly does. Even the interfaces to functions
4003 it exports seem to change occasionally. So programs compiled by GHC might only run with
4004 particular versions of Cygwin. All of this seems very undesirable.
4007 Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
4008 we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
4009 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
4013 <sect3><title>Summary</title>
4015 <para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
4016 how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
4017 by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
4019 <para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
4020 GHC-cygwin too is beyond our resources. The GHC we distribute
4021 therefore does not require Cygwin to run, nor do the programs it
4022 compiles require Cygwin.</para>
4024 <para>The instructions that follow describe how to build GHC-mingw. It is
4025 possible to build GHC-cygwin, but it's not a supported route, and the build system might
4030 <Sect2><Title>Installing and configuring Cygwin</Title>
4032 <para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
4033 but you do need it to <emphasis>build</emphasis> GHC.</para>
4035 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
4036 The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
4037 Both <command>cvs</command> and <command>ssh</command>
4038 come with Cygwin, but you'll need them, so make sure you select them when running
4039 the Cygwin installer.
4042 <para> Now set the following user environment variables:
4045 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
4046 <constant>PATH</constant></para></listitem>
4050 Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
4051 don't do this you get very weird messages when you type
4052 <Command>make</Command>, such as:
4054 /c: /c: No such file or directory
4059 <listitem><para> Set <constant>SHELL</constant> to
4060 <Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
4061 <constant>SHELL</constant> is what you get.
4064 <listitem><para> Set <constant>HOME</constant> to point to your
4065 home directory. This is where, for example,
4066 <command>bash</command> will look for your <filename>.bashrc</filename>
4067 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
4073 There are a few other things to do:
4077 Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
4078 (and similarly for <Command>bash</Command>). Notice the hardwired path!
4079 So you need to ensure that your <Filename>/bin</Filename> directory has the following
4082 <listitem> <para><Command>sh</Command></para></listitem>
4083 <listitem> <para><Command>perl</Command></para></listitem>
4084 <listitem> <para><Command>cat</Command></para></listitem>
4086 All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
4087 installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
4088 <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
4089 (You can discover where your Cygwin
4090 root directory <Filename>/</Filename> is by typing <Command>mount</Command>).
4091 Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
4092 directory, there's no need to copy anything.
4098 By default, cygwin provides the command shell <filename>ash</filename>
4099 as <filename>sh.exe</filename>. It has a couple of 'issues', so
4100 in your <filename>/bin</filename> directory, make sure that <filename>
4101 bash.exe</filename> is also provided as <filename>sh.exe</filename>
4102 (i.e. overwrite the old <filename>sh.exe</filename> with a copy of
4103 <filename>bash.exe</filename>).
4109 <para>Finally, here are some things to be aware of when using Cygwin:
4111 <listitem> <para>Cygwin doesn't deal well with filenames that include
4112 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
4116 <listitem> <para> Cygwin implements a symbolic link as a text file with some
4117 magical text in it. So other programs that don't use Cygwin's
4118 I/O libraries won't recognise such files as symlinks.
4119 In particular, programs compiled by GHC are meant to be runnable
4120 without having Cygwin, so they don't use the Cygwin library, so
4121 they don't recognise symlinks.
4125 Win32 has a <command>find</command> command which is not the same as Cygwin's find.
4126 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
4127 before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
4128 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
4129 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
4136 <Sect2><Title>Other things you need to install</Title>
4138 <para>You have to install the following other things to build GHC:
4142 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
4143 This is what you will use to compile GHC. Add it in your
4144 <constant>PATH</constant>: the installer tells you the path element
4145 you need to add upon completion.
4151 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
4152 Happy is a parser generator used to compile the Haskell grammar. Add it in your
4153 <constant>PATH</constant>.
4159 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
4160 generate code, so you have to install that. Just pick up a mingw bundle at
4161 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
4162 We install it in <filename>c:/mingw</filename>.
4168 <para> Finally, check out a copy of GHC sources from
4169 the CVS repository, following the instructions above (<xref linkend="cvs-access">).
4176 <Sect2><Title>Building GHC</Title>
4179 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
4180 the bullets below only tell
4181 you about Windows-specific wrinkles.</para>
4185 Run <Command>autoconf</Command> both in <filename>fptools</filename>
4186 and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
4187 get an error when you run <filename>./configure</filename>:
4190 creating mk/config.h
4191 mk/config.h is unchanged
4193 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
4194 ./configure: ./configure: No such file or directory
4195 configure: error: ./configure failed for ghc
4200 <listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
4201 read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
4204 /usr/bin/autoconf: cannot create configure: permission denied
4206 Solution: delete <filename>configure</filename> first.
4211 You either need to add <filename>ghc</filename> to your
4212 <constant>PATH</constant> before you invoke
4213 <Command>configure</Command>, or use the <Command>configure</Command>
4214 option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
4220 After <command>autoconf</command> run <command>./configure</command> in
4221 <filename>fptools/</filename> thus:
4224 ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc
4226 This is the point at which you specify that you are building GHC-mingw
4227 (see <xref linkend="ghc-mingw">).
4229 Both these options are important! It's possible to get into
4230 trouble using the wrong C compiler!</para>
4233 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
4234 you'll have to do something more like:
4236 ./configure --with-gcc=...the Cygwin gcc...
4241 <listitem><para> Do not attempt to build the documentation.
4242 It needs all kinds of wierd Jade stuff that we haven't worked out for
4243 Win32.</para></listitem>
projects / ghc-hetmet.git / blob