1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
7 <Title>Building and Installing the Glasgow Functional Programming Tools Suite
9 <Author><OtherName>The GHC Team</OtherName></Author>
10 <Address><Email>glasgow-haskell-{users,bugs}@dcs.gla.ac.uk</Email></Address>
11 <PubDate>January 2000</PubDate>
16 This guide is intended for people who want to build or modify
17 programs from the Glasgow <Literal>fptools</Literal> suite (as distinct from those
18 who merely want to <Emphasis>run</Emphasis> them). Installation instructions are now provided in the user guide.
22 The bulk of this guide applies to building on Unix systems; see <XRef LinkEnd="winbuild"> for Windows notes.
30 <Sect1 id="sec-getting">
31 <Title>Getting the Glasgow <Literal>fptools</Literal> suite
35 Building the Glasgow tools <Emphasis>can</Emphasis> be complicated, mostly because
36 there are so many permutations of what/why/how, e.g., ``Build Happy
37 with HBC, everything else with GHC, leave out profiling, and test it
38 all on the `real' NoFib programs.'' Yeeps!
42 Happily, such complications don't apply to most people. A few common
43 ``strategies'' serve most purposes. Pick one and proceed
51 <Term><IndexTerm><Primary>Binary distribution</Primary></IndexTerm>.</Term>
54 If your only purpose is to install some of the <Literal>fptools</Literal> suite then the easiest thing to do is to get a binary distribution. In the
55 binary distribution everything is pre-compiled for your particular
56 machine architecture and operating system, so all you should have to
57 do is install the binaries and libraries in suitable places. The user guide
58 describes how to do this.
62 A binary distribution may not work for you for two reasons. First, we
63 may not have built the suite for the particular architecture/OS
64 platform you want. That may be due to lack of time and energy (in
65 which case you can get a source distribution and build from it; see
66 below). Alternatively, it may be because we haven't yet ported the
67 suite to your architecture, in which case you are considerably worse
72 The second reason a binary distribution may not be what you want is
73 if you want to read or modify the souce code.
75 </ListItem></VarListEntry>
77 <Term><IndexTerm><Primary>Source distribution</Primary></IndexTerm>.</Term>
81 platform, but (a) you like the warm fuzzy feeling of compiling things
82 yourself; (b) you want to build something ``extra''—e.g., a set of
83 libraries with strictness-analysis turned off; or (c) you want to hack
88 A source distribution contains complete sources for one or more
89 projects in the <Literal>fptools</Literal> suite. Not only that, but the more awkward
90 machine-independent steps are done for you. For example, if you don't
91 have <Command>flex</Command><IndexTerm><Primary>flex</Primary></IndexTerm> you'll find it convenient that the source
92 distribution contains the result of running <Command>flex</Command> on the lexical
93 analyser specification. If you don't want to alter the lexical
94 analyser then this saves you having to find and install <Command>flex</Command>. You
95 will still need a working version of GHC on your machine in order to
96 compile (most of) the sources, however.
100 We make source distributions more frequently than binary
101 distributions; a release that comes with pre-compiled binaries
102 is considered a major release, i.e., a release that we have some
103 confidence will work well by having tested it (more) thoroughly.
107 Source-only distributions are either bugfix releases or snapshots of
108 current state of development. The release has undergone some testing.
109 Source releases of 4.xx can be compiled up using 2.10 or later.
111 </ListItem></VarListEntry>
113 <Term>Build GHC from intermediate C <Filename>.hc</Filename> files<IndexTerm><Primary>hc files</Primary></IndexTerm>:</Term>
117 need a working GHC to use a source distribution. What if you don't
118 have a working GHC? Then you have no choice but to ``bootstrap'' up
119 from the intermediate C (<Filename>.hc</Filename>) files that we provide. Building GHC
120 on an unsupported platform falls into this category. Please see
121 <Xref LinkEnd="sec-booting-from-C">.
125 Once you have built GHC, you can build the other Glasgow tools with
130 In theory, you can (could?) build GHC with another Haskell compiler
131 (e.g., HBC). We haven't tried to do this for ages and it almost
132 certainly doesn't work any more (for tedious reasons).
134 </ListItem></VarListEntry>
136 <Term>The CVS repository.</Term>
139 We make source distributions slightly more often than binary
140 distributions; but still infrequently. If you want more up-to-the
141 minute (but less tested) source code then you need to get access to
146 All the <Literal>fptools</Literal> source code is held in a CVS repository. CVS is a
147 pretty good source-code control system, and best of all it works over
152 The repository holds source code only. It holds no mechanically
153 generated files at all. So if you check out a source tree from CVS
154 you will need to install every utility so that you can build all the
155 derived files from scratch.
159 More information about our CVS repository is available at <ULink
160 URL="http://www.dcs.gla.ac.uk/fp/software/ghc/cvs-cheat-sheet.html"
161 >The Fptools CVS Cheat Sheet</ULink
164 </ListItem></VarListEntry>
169 If you are going to do any building from sources (either from a source
170 distribution or the CVS repository) then you need to read all of this
177 <Title>Things to check before you start typing</Title>
180 Here's a list of things to check before you get started.
186 <IndexTerm><Primary>Disk space needed</Primary></IndexTerm>: About 30MB (five hamburgers' worth) of disk space
187 for the most basic binary distribution of GHC; more for some
188 platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
189 Haskell libraries) might take you to 8–10 hamburgers.
191 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
192 build the basic stuff from scratch.
195 All of the above are <Emphasis>estimates</Emphasis> of disk-space needs. (I don't yet
196 know the disk requirements for the non-GHC tools).
203 Use an appropriate machine, compilers, and things.
205 SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
206 or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
207 in pretty good shape. <Xref LinkEnd="sec-port-info">
208 gives the full run-down on ports or lack thereof.
210 NOTE: as of version 4.00, we lost a few ports. All of the x86 ports
211 are working, as is the Sparc/Solaris port, but the rest will need a
212 little work. Please contact us if you can provide hardware cycles
213 and/or porting expertise.
220 Be sure that the ``pre-supposed'' utilities are installed.
221 <Xref LinkEnd="sec-pre-supposed"> elaborates.
228 If you have any problem when building or installing the Glasgow
229 tools, please check the ``known pitfalls'' (<Xref LinkEnd="sec-build-pitfalls">). Also check the <ULink
230 URL="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html"
231 >known bugs page</ULink>.
232 <IndexTerm><Primary>known bugs</Primary></IndexTerm>
233 <IndexTerm><Primary>bugs, known</Primary></IndexTerm>
235 If you feel there is still some shortcoming in our procedure or
236 instructions, please report it.
238 For GHC, please see the bug-reporting section of the User's guide
239 (separate document), to maximise the usefulness of your report.
240 <IndexTerm><Primary>bugs, reporting</Primary></IndexTerm>
242 If in doubt, please send a message to <Email>glasgow-haskell-bugs@dcs.gla.ac.uk</Email>.
243 <IndexTerm><Primary>bugs, mailing list</Primary></IndexTerm>
253 <Sect1 id="sec-port-info">
254 <Title>What machines the Glasgow tools run on
258 <IndexTerm><Primary>ports, GHC</Primary></IndexTerm>
259 <IndexTerm><Primary>GHC ports</Primary></IndexTerm>
260 <IndexTerm><Primary>supported platforms</Primary></IndexTerm>
261 <IndexTerm><Primary>platforms, supported</Primary></IndexTerm>
265 The main question is whether or not the Haskell compiler (GHC) runs on
270 A ``platform'' is a architecture/manufacturer/operating-system
271 combination, such as <Literal>sparc-sun-solaris2</Literal>. Other common ones are
272 <Literal>alpha-dec-osf2</Literal>, <Literal>hppa1.1-hp-hpux9</Literal>, <Literal>i386-unknown-linux</Literal>,
273 <Literal>i386-unknown-solaris2</Literal>, <Literal>i386-unknown-freebsd</Literal>,
274 <Literal>i386-unknown-cygwin32</Literal>, <Literal>m68k-sun-sunos4</Literal>, <Literal>mips-sgi-irix5</Literal>,
275 <Literal>sparc-sun-sunos4</Literal>, <Literal>sparc-sun-solaris2</Literal>, <Literal>powerpc-ibm-aix</Literal>.
279 Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
280 work on all machines for which basic Haskell compiling is supported.
284 Some libraries may only work on a limited number of platforms; for
285 example, a sockets library is of no use unless the operating system
286 supports the underlying BSDisms.
290 <Title>What platforms the Haskell compiler (GHC) runs on</Title>
293 <IndexTerm><Primary>fully-supported platforms</Primary></IndexTerm>
294 <IndexTerm><Primary>native-code generator</Primary></IndexTerm>
295 <IndexTerm><Primary>registerised ports</Primary></IndexTerm>
296 <IndexTerm><Primary>unregisterised ports</Primary></IndexTerm>
300 The GHC hierarchy of Porting Goodness: (a) Best is a native-code
301 generator; (b) next best is a ``registerised''
302 port; (c) the bare minimum is an ``unregisterised'' port.
303 (``Unregisterised'' is so terrible that we won't say more about it).
307 We use Sparcs running Solaris 2.5, x86 boxes running FreeBSD and
308 Linux, and DEC Alphas running OSF/1 V2.0, so those are the
309 ``fully-supported'' platforms, unsurprisingly. All have native-code
310 generators, for quicker compilations. The native-code generator for
311 iX86 platforms (e.g., Linux ELF) is <Emphasis>nearly</Emphasis> working; but is not
312 turned on by default.
316 Here's everything that's known about GHC ports. We identify platforms
317 by their ``canonical'' CPU/Manufacturer/OS triple.
321 Note that some ports are fussy about which GCC version you use; or
322 require GAS; or…
329 <Term>alpha-dec-osf1:</Term>
332 <IndexTerm><Primary>alpha-dec-osf1: fully supported</Primary></IndexTerm>
336 (We have OSF/1 V3.0.) Fully supported, including native-code
337 generator. We recommend GCC 2.6.x or later.
339 </ListItem></VarListEntry>
341 <Term>sparc-sun-sunos4:</Term>
344 <IndexTerm><Primary>sparc-sun-sunos4: fully supported</Primary></IndexTerm>
348 Fully supported, including native-code generator.
350 </ListItem></VarListEntry>
352 <Term>sparc-sun-solaris2:</Term>
355 <IndexTerm><Primary>sparc-sun-solaris2: fully supported</Primary></IndexTerm>
359 Fully supported, including native-code generator. A couple of quirks,
360 though: (a) the profiling libraries are bizarrely huge when compiled
361 with object splitting; (b) the default <Command>xargs</Command><IndexTerm><Primary>xargs</Primary></IndexTerm> program is
362 atrociously bad for building GHC libraries (see <Xref LinkEnd="sec-pre-supposed"> for
365 </ListItem></VarListEntry>
367 <Term>HP-PA box running HP</Term>
371 <IndexTerm><Primary>hppa1.1-hp-hpux: registerised port</Primary></IndexTerm>
375 Works registerised. No native-code generator. For GCC, you're best
376 off with one of the Utah releases of GCC 2.6.3 (`u3' or later), from
377 <Literal>jaguar.cs.utah.edu</Literal>. We think a straight GCC 2.7.x works,
382 Concurrent/Parallel Haskell probably don't work (yet).
383 <IndexTerm><Primary>hppa1.1-hp-hpux: concurrent—no</Primary></IndexTerm>
384 <IndexTerm><Primary>hppa1.1-hp-hpux: parallel—no</Primary></IndexTerm>
386 </ListItem></VarListEntry>
388 <Term>i386-*-linux (PCs running Linux—ELF format):</Term>
391 <IndexTerm><Primary>i386-*-linux: registerised port</Primary></IndexTerm>
395 GHC works registerised. You <Emphasis>must</Emphasis> have GCC 2.7.x or later. The
396 iX86 native-code generator is <Emphasis>nearly</Emphasis> there, but it isn't turned
401 Profiling works, and Concurrent Haskell works.
402 <IndexTerm><Primary>i386-*-linux: profiling—yes</Primary></IndexTerm>
403 <IndexTerm><Primary>i386-*-linux: concurrent—yes</Primary></IndexTerm>
404 Parallel Haskell probably works.
405 <IndexTerm><Primary>i386-*-linux: parallel—maybe</Primary></IndexTerm>
409 On old Linux a.out systems: should be the same.
410 <IndexTerm><Primary>i386-*-linuxaout: registerised port</Primary></IndexTerm>
412 </ListItem></VarListEntry>
414 <Term>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and
415 NetBSD/OpenBSD using FreeBSD emulation):</Term>
418 <IndexTerm><Primary>i386-*-freebsd:registerised port</Primary></IndexTerm>
422 GHC works registerised. Supports same set of bundles as the above.
426 <IndexTerm><Primary>i386-*-freebsd: profiling—yes</Primary></IndexTerm>
427 <IndexTerm><Primary>i386-*-freebsd: concurrent—yes</Primary></IndexTerm>
428 <IndexTerm><Primary>i386-*-freebsd: parallel—maybe</Primary></IndexTerm>
430 </ListItem></VarListEntry>
432 <Term>i386-unknown-cygwin32:</Term>
435 <IndexTerm><Primary>i386-unknown-cygwin32: fully supported</Primary></IndexTerm>
439 Fully supported under Win95/NT, including a native code
440 generator. Requires the <Literal>cygwin32</Literal> compatibility library and a
441 healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
442 Profiling works, so does Concurrent Haskell.
446 <IndexTerm><Primary>i386-*-cygwin32: profiling—yes</Primary></IndexTerm>
447 <IndexTerm><Primary>i386-*-cygwin32: concurrent—yes</Primary></IndexTerm>
449 </ListItem></VarListEntry>
451 <Term>mips-sgi-irix5:</Term>
454 <IndexTerm><Primary>mips-sgi-irix5: registerised port</Primary></IndexTerm>
458 GHC works registerised (no native-code generator). I suspect any
459 GCC 2.6.x (or later) is OK. The GCC that I used was built with
460 <Option>--with-gnu-as</Option>; turns out that is important!
464 Concurrent/Parallel Haskell probably don't work (yet).
465 Profiling might work, but it is untested.
466 <IndexTerm><Primary>mips-sgi-irix5: concurrent—no</Primary></IndexTerm>
467 <IndexTerm><Primary>mips-sgi-irix5: parallel—no</Primary></IndexTerm>
468 <IndexTerm><Primary>mips-sgi-irix5: profiling—maybe</Primary></IndexTerm>
470 </ListItem></VarListEntry>
472 <Term>mips-sgi-irix6:</Term>
475 <IndexTerm><Primary>mips-sgi-irix6: registerised port</Primary></IndexTerm>
479 Thanks to the fine efforts of Tomasz Cholewo <ULink
480 URL="mailto:tjchol01@mecca.spd.louisville.edu"
481 >tjchol01@mecca.spd.louisville.edu</ULink
482 >, GHC works registerised (no
483 native code generator) under IRIX 6.2 and 6.3. Depends on having a
485 URL="http://mecca.spd.louisville.edu/~tjchol01/software/"
486 >specially tweaked version of gcc-2.7.2 around</ULink>.
490 Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
491 <IndexTerm><Primary>mips-sgi-irix6: concurrent—maybe</Primary></IndexTerm>
492 <IndexTerm><Primary>mips-sgi-irix6: parallel—maybe</Primary></IndexTerm>
493 <IndexTerm><Primary>mips-sgi-irix6: profiling—yes</Primary></IndexTerm>
495 </ListItem></VarListEntry>
497 <Term>powerpc-ibm-aix:</Term>
500 <IndexTerm><Primary>powerpc-ibm-aix: registerised port</Primary></IndexTerm>
501 GHC works registerised (no native-code generator…yet).
502 I suspect 2.7.x is what you need together with this.
506 Concurrent/Parallel Haskell probably don't work (yet).
507 Profiling might work, but it is untested.
508 <IndexTerm><Primary>mips-sgi-irix5: concurrent—no</Primary></IndexTerm>
509 <IndexTerm><Primary>mips-sgi-irix5: parallel—no</Primary></IndexTerm>
510 <IndexTerm><Primary>mips-sgi-irix5: profiling—maybe</Primary></IndexTerm>
512 </ListItem></VarListEntry>
514 <Term>m68k-apple-macos7 (Mac, using MPW):</Term>
517 <IndexTerm><Primary>m68k-apple-macos7: historically ported</Primary></IndexTerm>
518 Once upon a time, David Wright in Tasmania has actually
519 gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
520 You may be able to get Thomson's from here. (Not sure that it will
521 excite you to death, but…)
525 No particularly recent GHC is known to work on a Mac.
527 </ListItem></VarListEntry>
529 <Term>m68k-next-nextstep3:</Term>
532 <IndexTerm><Primary>m68k-next-nextstep3: historically ported</Primary></IndexTerm>
533 Carsten Schultz succeeded with a ``registerised'' port of GHC 0.29.
534 There's probably a little bit-rot since then, but otherwise it should
539 Concurrent/Parallel Haskell probably won't work (yet).
540 <IndexTerm><Primary>m68k-next-nextstep3: concurrent—no</Primary></IndexTerm>
541 <IndexTerm><Primary>m68k-next-nextstep3: parallel—no</Primary></IndexTerm>
543 </ListItem></VarListEntry>
545 <Term>m68k-sun-sunos4 (Sun3):</Term>
548 <IndexTerm><Primary>m68k-sun-sunos4: registerised
549 port</Primary></IndexTerm> GHC 2.0x and 3.0x haven't been tried on a Sun3. GHC 0.26
550 worked registerised. No native-code generator.
554 Concurrent/Parallel Haskell probably don't work (yet).
555 <IndexTerm><Primary>m68k-sun-sunos4: concurrent—no</Primary></IndexTerm>
556 <IndexTerm><Primary>m68k-sun-sunos4: parallel—no</Primary></IndexTerm>
558 </ListItem></VarListEntry>
565 <Title>What machines the other tools run on</Title>
568 Unless you hear otherwise, the other tools work if GHC works.
572 Haggis requires Concurrent Haskell to work.
573 <IndexTerm><Primary>Haggis, Concurrent Haskell</Primary></IndexTerm>
581 <Sect1 id="sec-pre-supposed">
582 <Title>Installing pre-supposed utilities
584 <IndexTerm><Primary>pre-supposed utilities</Primary></IndexTerm>
585 <IndexTerm><Primary>utilities, pre-supposed</Primary></IndexTerm></Title>
588 Here are the gory details about some utility programs you may need;
589 <Command>perl</Command> and <Command>gcc</Command> are the only important ones. (PVM<IndexTerm><Primary>PVM</Primary></IndexTerm> is important
590 if you're going for Parallel Haskell.) The <Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
591 script will tell you if you are missing something.
601 <IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
602 <IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>
603 <Emphasis>You have to have Perl to proceed!</Emphasis> Perl is a language quite good
604 for doing shell-scripty tasks that involve lots of text processing.
605 It is pretty easy to install.
609 Perl 5 is required. For Win32 platforms, we strongly suggest you pick
610 up a port of Perl 5 for <Literal>cygwin32</Literal>, as the common Hip/ActiveWare port
611 of Perl is Not Cool Enough for our purposes.
615 Perl should be put somewhere so that it can be invoked by the <Literal>#!</Literal>
616 script-invoking mechanism. (I believe <Filename>/usr/bin/perl</Filename> is preferred;
617 we use <Filename>/usr/local/bin/perl</Filename> at Glasgow.) The full pathname should
618 may need to be less than 32 characters long on some systems.
620 </ListItem></VarListEntry>
622 <Term>GNU C (<Command>gcc</Command>):</Term>
625 <IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm>
626 <IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm>
630 Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other
631 versions at your own risk!
635 If your GCC dies with ``internal error'' on some GHC source file,
636 please let us know, so we can report it and get things improved.
637 (Exception: on iX86 boxes—you may need to fiddle with GHC's
638 <Option>-monly-N-regs</Option> option; see the User's Guide)
640 </ListItem></VarListEntry>
642 <Term><Command>xargs</Command> on Solaris2:</Term>
645 <IndexTerm><Primary>xargs, presupposed (Solaris only)</Primary></IndexTerm>
646 <IndexTerm><Primary>Solaris: alternative xargs</Primary></IndexTerm>
647 The GHC libraries are put together with something like:
650 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
653 Unfortunately the Solaris <Command>xargs</Command> (the shell-script equivalent
654 of <Function>map</Function>) only ``bites off'' the <Filename>.o</Filename> files a few at a
655 time—with near-infinite rebuilding of the symbol table in
656 the <Filename>.a</Filename> file.
660 The best solution is to install a sane <Command>xargs</Command> from the GNU
661 findutils distribution. You can unpack, build, and install the GNU
662 version in the time the Solaris <Command>xargs</Command> mangles just one GHC
665 </ListItem></VarListEntry>
667 <Term>Autoconf:</Term>
670 <IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
671 <IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>
675 GNU Autoconf is needed if you intend to build from the CVS sources, it
676 is <Emphasis>not</Emphasis> needed if you just intend to build a standard source
681 Autoconf builds the <Command>configure</Command> script from <Filename>configure.in</Filename> and
682 <Filename>aclocal.m4</Filename>. If you modify either of these files, you'll need
683 Autoconf to rebuild <Filename>configure</Filename>.
685 </ListItem></VarListEntry>
687 <Term><Command>sed</Command></Term>
690 <IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm>
691 <IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm>
692 You need a working <Command>sed</Command> if you are going to build from sources. The
693 build-configuration stuff needs it. GNU sed version 2.0.4 is no good!
694 It has a bug in it that is tickled by the build-configuration. 2.0.5
695 is OK. Others are probably OK too (assuming we don't create too
696 elaborate configure scripts.)
698 </ListItem></VarListEntry>
703 One <Literal>fptools</Literal> project is worth a quick note at this point, because it
704 is useful for all the others: <Literal>glafp-utils</Literal> contains several utilities
705 which aren't particularly Glasgow-ish, but Occasionally Indispensable.
706 Like <Command>lndir</Command> for creating symbolic link trees.
709 <Sect2 id="pre-supposed-gph-tools">
710 <Title>Tools for building parallel GHC (GPH)
717 <Term>PVM version 3:</Term>
720 <IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
721 <IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>
725 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
726 run. (You only need this if you plan to run Parallel Haskell.
727 Concurent Haskell, which runs concurrent threads on a uniprocessor
728 doesn't need it.) Underneath PVM, you can have (for example) a
729 network of workstations (slow) or a multiprocessor box (faster).
733 The current version of PVM is 3.3.11; we use 3.3.7. It is readily
734 available on the net; I think I got it from <Literal>research.att.com</Literal>, in
735 <Filename>netlib</Filename>.
739 A PVM installation is slightly quirky, but easy to do. Just follow
740 the <Filename>Readme</Filename> instructions.
742 </ListItem></VarListEntry>
744 <Term><Command>bash</Command>:</Term>
747 <IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>
748 Sadly, the <Command>gr2ps</Command> script, used to convert ``parallelism profiles''
749 to PostScript, is written in Bash (GNU's Bourne Again shell).
750 This bug will be fixed (someday).
752 </ListItem></VarListEntry>
758 <Sect2 id="pre-supposed-doc-tools">
759 <Title>Tools for building the Documentation
763 The following additional tools are required if you want to format the
764 documentation that comes with the <Literal>fptools</Literal> projects:
771 <Term>DocBook:</Term>
774 <IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
775 <IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>
776 All our documentation is written in SGML, using the DocBook DTD and processed using the <ULink URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook tools</ULink>, which is the most shrink-wrapped SGML suite
777 that we could find. Unfortunately, it's only packaged as RPMs. You can use it to generate HTML (and
778 hence DVI, PDF and Postscript) and RTF from any
779 LinuxDoc source file (including this manual).
781 </ListItem></VarListEntry>
786 <IndexTerm><Primary>pre-supposed: TeX</Primary></IndexTerm>
787 <IndexTerm><Primary>TeX, pre-supposed</Primary></IndexTerm>
788 A decent TeX distribution is required if you want to produce printable
789 documentation. We recomment teTeX, which includes just about
792 </ListItem></VarListEntry>
798 <Sect2 id="pre-supposed-other-tools">
799 <Title>Other useful tools
809 <IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm>
810 <IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>
814 This is a quite-a-bit-better-than-Lex lexer. Used to build a couple
815 of utilities in <Literal>glafp-utils</Literal>. Depending on your operating system,
816 the supplied <Command>lex</Command> may or may not work; you should get the GNU
819 </ListItem></VarListEntry>
827 <Sect1 id="sec-building-from-source">
828 <Title>Building from source
830 <IndexTerm><Primary>Building from source</Primary></IndexTerm>
831 <IndexTerm><Primary>Source, building from</Primary></IndexTerm></Title>
834 You've been rash enough to want to build some of
835 the Glasgow Functional Programming tools (GHC, Happy,
836 nofib, etc.) from source. You've slurped the source,
837 from the CVS repository or from a source distribution, and
838 now you're sitting looking at a huge mound of bits, wondering
843 Gingerly, you type <Command>make</Command>. Wrong already!
847 This rest of this guide is intended for duffers like me, who aren't
848 really interested in Makefiles and systems configurations, but who
849 need a mental model of the interlocking pieces so that they can make
850 them work, extend them consistently when adding new software, and lay
851 hands on them gently when they don't work.
854 <Sect2 id="sec-source-tree">
855 <Title>Your source tree
859 The source code is held in your <Emphasis>source tree</Emphasis>.
860 The root directory of your source tree <Emphasis>must</Emphasis>
861 contain the following directories and files:
870 <Filename>Makefile</Filename>: the root Makefile.
876 <Filename>mk/</Filename>: the directory that contains the
877 main Makefile code, shared by all the
878 <Literal>fptools</Literal> software.
884 <Filename>configure.in</Filename>, <Filename>config.sub</Filename>, <Filename>config.guess</Filename>:
885 these files support the configuration process.
891 <Filename>install-sh</Filename>.
900 All the other directories are individual <Emphasis>projects</Emphasis> of the
901 <Literal>fptools</Literal> system—for example, the Glasgow Haskell Compiler
902 (<Literal>ghc</Literal>), the Happy parser generator (<Literal>happy</Literal>), the <Literal>nofib</Literal> benchmark
903 suite, and so on. You can have zero or more of these. Needless to
904 say, some of them are needed to build others.
908 The important thing to remember is that even if you want only one
909 project (<Literal>happy</Literal>, say), you must have a source tree whose root
910 directory contains <Filename>Makefile</Filename>, <Filename>mk/</Filename>, <Filename>configure.in</Filename>, and the
911 project(s) you want (<Filename>happy/</Filename> in this case). You cannot get by with
912 just the <Filename>happy/</Filename> directory.
919 <IndexTerm><Primary>build trees</Primary></IndexTerm>
920 <IndexTerm><Primary>link trees, for building</Primary></IndexTerm></Title>
923 While you can build a system in the source tree, we don't recommend it.
924 We often want to build multiple versions of our software
925 for different architectures, or with different options (e.g. profiling).
926 It's very desirable to share a single copy of the source code among
931 So for every source tree we have zero or more <Emphasis>build trees</Emphasis>. Each
932 build tree is initially an exact copy of the source tree, except that
933 each file is a symbolic link to the source file, rather than being a
934 copy of the source file. There are ``standard'' Unix utilities that
935 make such copies, so standard that they go by different names:
936 <Command>lndir</Command><IndexTerm><Primary>lndir</Primary></IndexTerm>, <Command>mkshadowdir</Command><IndexTerm><Primary>mkshadowdir</Primary></IndexTerm> are two (If you
937 don't have either, the source distribution includes sources for the
938 X11 <Command>lndir</Command>—check out <Filename>fptools/glafp-utils/lndir</Filename>). See <Xref LinkEnd="sec-storysofar"> for a typical invocation.
942 The build tree does not need to be anywhere near the source tree in
943 the file system. Indeed, one advantage of separating the build tree
944 from the source is that the build tree can be placed in a
945 non-backed-up partition, saving your systems support people from
946 backing up untold megabytes of easily-regenerated, and
947 rapidly-changing, gubbins. The golden rule is that (with a single
948 exception—<XRef LinkEnd="sec-build-config"> <Emphasis>absolutely everything in the build tree is either
949 a symbolic link to the source tree, or else is mechanically
950 generated</Emphasis>. It should be perfectly OK for your build tree to vanish
951 overnight; an hour or two compiling and you're on the road again.
955 You need to be a bit careful, though, that any new files you create
956 (if you do any development work) are in the source tree, not a build tree!
960 Remember, that the source files in the build tree are <Emphasis>symbolic
961 links</Emphasis> to the files in the source tree. (The build tree soon
962 accumulates lots of built files like <Filename>Foo.o</Filename>, as well.) You
963 can <Emphasis>delete</Emphasis> a source file from the build tree without affecting
964 the source tree (though it's an odd thing to do). On the other hand,
965 if you <Emphasis>edit</Emphasis> a source file from the build tree, you'll edit the
966 source-tree file directly. (You can set up Emacs so that if you edit
967 a source file from the build tree, Emacs will silently create an
968 edited copy of the source file in the build tree, leaving the source
969 file unchanged; but the danger is that you think you've edited the
970 source file whereas actually all you've done is edit the build-tree
971 copy. More commonly you do want to edit the source file.)
975 Like the source tree, the top level of your build tree must be (a
976 linked copy of) the root directory of the <Literal>fptools</Literal> suite. Inside
977 Makefiles, the root of your build tree is called
978 <Constant>$(FPTOOLS_TOP)</Constant><IndexTerm><Primary>FPTOOLS_TOP</Primary></IndexTerm>. In the rest of this document path
979 names are relative to <Constant>$(FPTOOLS_TOP)</Constant> unless otherwise stated. For
980 example, the file <Filename>ghc/mk/target.mk</Filename> is actually
981 <Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc/mk/target.mk</Filename>.
986 <Sect2 id="sec-build-config">
987 <Title>Getting the build you want
991 When you build <Literal>fptools</Literal> you will be compiling code on a particular
992 <Emphasis>host platform</Emphasis>, to run on a particular <Emphasis>target platform</Emphasis>
993 (usually the same as the host platform)<IndexTerm><Primary>platform</Primary></IndexTerm>. The
994 difficulty is that there are minor differences between different
995 platforms; minor, but enough that the code needs to be a bit different
996 for each. There are some big differences too: for a different
997 architecture we need to build GHC with a different native-code
1002 There are also knobs you can turn to control how the <Literal>fptools</Literal>
1003 software is built. For example, you might want to build GHC optimised
1004 (so that it runs fast) or unoptimised (so that you can compile it fast
1005 after you've modified it. Or, you might want to compile it with
1006 debugging on (so that extra consistency-checking code gets included)
1011 All of this stuff is called the <Emphasis>configuration</Emphasis> of your build.
1012 You set the configuration using a three-step process.
1016 <Term>Step 1: get ready for configuration.</Term>
1020 <Constant>$(FPTOOLS_TOP)</Constant> and issue the command <Command>autoconf</Command><IndexTerm><Primary>autoconf</Primary></IndexTerm> (with
1021 no arguments). This GNU program converts <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure.in</Filename>
1022 to a shell script called <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure</Filename>.
1026 Both these steps are completely platform-independent; they just mean
1027 that the human-written file (<Filename>configure.in</Filename>) can be short, although
1028 the resulting shell script, <Command>configure</Command>, and <Filename>mk/config.h.in</Filename>, are
1033 In case you don't have <Command>autoconf</Command> we distribute the results,
1034 <Command>configure</Command>, and <Filename>mk/config.h.in</Filename>, with the source distribution. They
1035 aren't kept in the repository, though.
1037 </ListItem></VarListEntry>
1039 <Term>Step 2: system configuration.</Term>
1042 Runs the newly-created <Command>configure</Command> script, thus:
1048 <Command>configure</Command>'s mission is to scurry round your computer working out
1049 what architecture it has, what operating system, whether it has the
1050 <Function>vfork</Function> system call, where <Command>yacc</Command> is kept, whether <Command>gcc</Command> is available,
1051 where various obscure <Literal>#include</Literal> files are, whether it's a leap year,
1052 and what the systems manager had for lunch. It communicates these
1053 snippets of information in two ways:
1062 It translates <Filename>mk/config.mk.in</Filename><IndexTerm><Primary>config.mk.in</Primary></IndexTerm> to
1063 <Filename>mk/config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm>, substituting for things between
1064 ``<Literal>@</Literal>'' brackets. So, ``<Literal>@HaveGcc@</Literal>'' will be replaced by
1065 ``<Literal>YES</Literal>'' or ``<Literal>NO</Literal>'' depending on what <Command>configure</Command> finds.
1066 <Filename>mk/config.mk</Filename> is included by every Makefile (directly or indirectly),
1067 so the configuration information is thereby communicated to all
1075 It translates <Filename>mk/config.h.in</Filename><IndexTerm><Primary>config.h.in</Primary></IndexTerm> to
1076 <Filename>mk/config.h</Filename><IndexTerm><Primary>config.h</Primary></IndexTerm>. The latter is <Literal>#include</Literal>d by various C
1077 programs, which can thereby make use of configuration information.
1087 <Command>configure</Command> caches the results of its run in <Filename>config.cache</Filename>. Quite
1088 often you don't want that; you're running <Command>configure</Command> a second time
1089 because something has changed. In that case, simply delete
1090 <Filename>config.cache</Filename>.
1092 </ListItem></VarListEntry>
1094 <Term>Step 3: build configuration.</Term>
1097 Next, you say how this build of <Literal>fptools</Literal> is to differ from the
1098 standard defaults by creating a new file <Filename>mk/build.mk</Filename><IndexTerm><Primary>build.mk</Primary></IndexTerm>
1099 <Emphasis>in the build tree</Emphasis>. This file is the one and only file you edit
1100 in the build tree, precisely because it says how this build differs
1101 from the source. (Just in case your build tree does die, you might
1102 want to keep a private directory of <Filename>build.mk</Filename> files, and use a
1103 symbolic link in each build tree to point to the appropriate one.) So
1104 <Filename>mk/build.mk</Filename> never exists in the source tree—you create one in
1105 each build tree from the template. We'll discuss what to put in it
1108 </ListItem></VarListEntry>
1113 And that's it for configuration. Simple, eh?
1117 What do you put in your build-specific configuration file
1118 <Filename>mk/build.mk</Filename>? <Emphasis>For almost all purposes all you will do is put
1119 make variable definitions that override those in</Emphasis> <Filename>mk/config.mk.in</Filename>.
1120 The whole point of <Filename>mk/config.mk.in</Filename>—and its derived counterpart
1121 <Filename>mk/config.mk</Filename>—is to define the build configuration. It is heavily
1122 commented, as you will see if you look at it. So generally, what you
1123 do is look at <Filename>mk/config.mk.in</Filename>, and add definitions in <Filename>mk/build.mk</Filename>
1124 that override any of the <Filename>config.mk</Filename> definitions that you want to
1125 change. (The override occurs because the main boilerplate file,
1126 <Filename>mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>, includes <Filename>build.mk</Filename> after
1127 <Filename>config.mk</Filename>.)
1131 For example, <Filename>config.mk.in</Filename> contains the definition:
1137 ProjectsToBuild = glafp-utils ghc hslibs
1143 The accompanying comment explains that this is the list of enabled
1144 projects; that is, if (after configuring) you type <Command>gmake all</Command> in
1145 <Constant>FPTOOLS_TOP</Constant> three specified projects will be made. If you want to
1146 add <Command>green-card</Command>, you can add this line to <Filename>build.mk</Filename>:
1152 ProjectsToBuild += green-card
1164 ProjectsToBuild = glafp-utils ghc green-card
1170 (GNU <Command>make</Command> allows existing definitions to have new text appended
1171 using the ``<Literal>+=</Literal>'' operator, which is quite a convenient feature.)
1175 When reading <Filename>config.mk.in</Filename>, remember that anything between
1176 ``@...@'' signs is going to be substituted by <Command>configure</Command>
1177 later. You <Emphasis>can</Emphasis> override the resulting definition if you want,
1178 but you need to be a bit surer what you are doing. For example,
1179 there's a line that says:
1191 This defines the Make variables <Constant>YACC</Constant> to the pathname for a <Command>yacc</Command> that
1192 <Command>configure</Command> finds somewhere. If you have your own pet <Command>yacc</Command> you want
1193 to use instead, that's fine. Just add this line to <Filename>mk/build.mk</Filename>:
1205 You do not <Emphasis>have</Emphasis> to have a <Filename>mk/build.mk</Filename> file at all; if you
1206 don't, you'll get all the default settings from <Filename>mk/config.mk.in</Filename>.
1210 You can also use <Filename>build.mk</Filename> to override anything that <Command>configure</Command> got
1211 wrong. One place where this happens often is with the definition of
1212 <Constant>FPTOOLS_TOP_ABS</Constant>: this variable is supposed to be the canonical path
1213 to the top of your source tree, but if your system uses an automounter
1214 then the correct directory is hard to find automatically. If you find
1215 that <Command>configure</Command> has got it wrong, just put the correct definition in
1216 <Filename>build.mk</Filename>.
1221 <Sect2 id="sec-storysofar">
1222 <Title>The story so far</Title>
1225 Let's summarise the steps you need to carry to get yourself
1226 a fully-configured build tree from scratch.
1235 Get your source tree from somewhere (CVS repository or source
1236 distribution). Say you call the root directory <Filename>myfptools</Filename> (it
1237 does not have to be called <Filename>fptools</Filename>). Make sure that you have
1238 the essential files (see <XRef LinkEnd="sec-source-tree">).
1245 Use <Command>lndir</Command> or <Command>mkshadowdir</Command> to create a build tree.
1249 mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1252 (N.B. <Command>mkshadowdir</Command>'s first argument is taken relative to its second.) You probably want to give the build tree a name that
1253 suggests its main defining characteristic (in your mind at least),
1254 in case you later add others.
1261 Change directory to the build tree. Everything is going
1262 to happen there now.
1265 cd /scratch/joe-bloggs/myfptools-sun4
1273 Prepare for system configuration:
1279 (You can skip this step if you are starting from a source distribution,
1280 and you already have <Filename>configure</Filename> and <Filename>mk/config.h.in</Filename>.)
1287 Do system configuration:
1299 Create the file <Filename>mk/build.mk</Filename>,
1300 adding definitions for your desired configuration options.
1311 You can make subsequent changes to <Filename>mk/build.mk</Filename> as often
1312 as you like. You do not have to run any further configuration
1313 programs to make these changes take effect.
1314 In theory you should, however, say <Command>gmake clean</Command>, <Command>gmake all</Command>,
1315 because configuration option changes could affect anything—but in practice you are likely to know what's affected.
1321 <Title>Making things</Title>
1324 At this point you have made yourself a fully-configured build tree,
1325 so you are ready to start building real things.
1329 The first thing you need to know is that
1330 <Emphasis>you must use GNU <Command>make</Command>, usually called <Command>gmake</Command>, not standard Unix <Command>make</Command></Emphasis>.
1331 If you use standard Unix <Command>make</Command> you will get all sorts of error messages
1332 (but no damage) because the <Literal>fptools</Literal> <Command>Makefiles</Command> use GNU <Command>make</Command>'s facilities
1338 <Sect2 id="sec-standard-targets">
1339 <Title>Standard Targets
1341 <IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm>
1342 <IndexTerm><Primary>makefile targets</Primary></IndexTerm></Title>
1345 In any directory you should be able to make the following:
1349 <Term><Literal>boot</Literal>:</Term>
1352 does the one-off preparation required to get ready for the real work.
1353 Notably, it does <Command>gmake depend</Command> in all directories that contain
1354 programs. It also builds the necessary tools for compilation to proceed.
1358 You should say <Command>gmake boot</Command> right after configuring your build tree,
1359 but note that this is a one-off, i.e., there's no need to re-do
1360 <Command>gmake boot</Command> if you should re-configure your build tree at a later
1361 stage (no harm caused if you do though).
1363 </ListItem></VarListEntry>
1365 <Term><Literal>all</Literal>:</Term>
1368 makes all the final target(s) for this Makefile.
1369 Depending on which directory you are in a ``final target'' may be an
1370 executable program, a library archive, a shell script, or a Postscript
1371 file. Typing <Command>gmake</Command> alone is generally the same as typing <Command>gmake all</Command>.
1373 </ListItem></VarListEntry>
1375 <Term><Literal>install</Literal>:</Term>
1378 installs the things built by <Literal>all</Literal>. Where does it
1379 install them? That is specified by <Filename>mk/config.mk.in</Filename>; you can
1380 override it in <Filename>mk/build.mk</Filename>.
1382 </ListItem></VarListEntry>
1384 <Term><Literal>uninstall</Literal>:</Term>
1387 reverses the effect of <Literal>install</Literal>.
1389 </ListItem></VarListEntry>
1391 <Term><Literal>clean</Literal>:</Term>
1394 remove all easily-rebuilt files.
1396 </ListItem></VarListEntry>
1398 <Term><Literal>veryclean</Literal>:</Term>
1401 remove all files that can be rebuilt at all.
1402 There's a danger here that you may remove a file that needs a more
1403 obscure utility to rebuild it (especially if you started from a source
1406 </ListItem></VarListEntry>
1408 <Term><Literal>check</Literal>:</Term>
1413 </ListItem></VarListEntry>
1418 All of these standard targets automatically recurse into
1419 sub-directories. Certain other standard targets do not:
1426 <Term><Literal>configure</Literal>:</Term>
1429 is only available in the root directory
1430 <Constant>$(FPTOOLS_TOP)</Constant>; it has been discussed in <XRef LinkEnd="sec-build-config">.
1432 </ListItem></VarListEntry>
1434 <Term><Literal>depend</Literal>:</Term>
1437 make a <Filename>.depend</Filename> file in each directory that needs
1438 it. This <Filename>.depend</Filename> file contains mechanically-generated dependency
1439 information; for example, suppose a directory contains a Haskell
1440 source module <Filename>Foo.lhs</Filename> which imports another module <Literal>Baz</Literal>.
1441 Then the generated <Filename>.depend</Filename> file will contain the dependency:
1453 which says that the object file <Filename>Foo.o</Filename> depends on the interface file
1454 <Filename>Baz.hi</Filename> generated by compiling module <Literal>Baz</Literal>. The <Filename>.depend</Filename> file is
1455 automatically included by every Makefile.
1457 </ListItem></VarListEntry>
1459 <Term><Literal>binary-dist</Literal>:</Term>
1462 make a binary distribution. This is the
1463 target we use to build the binary distributions of GHC and Happy.
1465 </ListItem></VarListEntry>
1467 <Term><Literal>dist</Literal>:</Term>
1470 make a source distribution. You must be in a
1471 linked build tree to make this target.
1473 </ListItem></VarListEntry>
1478 Most <Filename>Makefile</Filename>s have targets other than these. You can discover them by looking in the <Filename>Makefile</Filename> itself.
1485 <IndexTerm><Primary>fastmake</Primary></IndexTerm>
1486 <IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>
1487 <IndexTerm><Primary>FAST, makefile variable</Primary></IndexTerm></Title>
1490 Sometimes the dependencies get in the way: if you've made a small
1491 change to one file, and you're absolutely sure that it won't affect
1492 anything else, but you know that <Command>make</Command> is going to rebuild everything
1493 anyway, the following hack may be useful:
1505 This tells the make system to ignore dependencies and just build what
1506 you tell it to. In other words, it's equivalent to temporarily
1507 removing the <Filename>.depend</Filename> file in the current directory (where
1508 <Command>mkdependHS</Command> and friends store their dependency information).
1512 A bit of history: GHC used to come with a <Command>fastmake</Command> script that did
1513 the above job, but GNU make provides the features we need to do it
1514 without resorting to a script. Also, we've found that fastmaking is
1515 less useful since the advent of GHC's recompilation checker (see the
1516 User's Guide section on "Separate Compilation").
1524 <Title>The <Filename>Makefile</Filename> architecture
1525 <IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
1528 <Command>make</Command> is great if everything works—you type <Command>gmake install</Command> and
1529 lo! the right things get compiled and installed in the right places.
1530 Our goal is to make this happen often, but somehow it often doesn't;
1531 instead some weird error message eventually emerges from the bowels of
1532 a directory you didn't know existed.
1536 The purpose of this section is to give you a road-map to help you figure
1537 out what is going right and what is going wrong.
1541 <Title>A small project</Title>
1544 To get started, let us look at the <Filename>Makefile</Filename> for an imaginary small
1545 <Literal>fptools</Literal> project, <Literal>small</Literal>. Each project in <Literal>fptools</Literal> has its own
1546 directory in <Constant>FPTOOLS_TOP</Constant>, so the <Literal>small</Literal> project will have its own
1547 directory <Constant>FPOOLS_TOP/small/</Constant>. Inside the <Filename>small/</Filename> directory there
1548 will be a <Filename>Makefile</Filename>, looking something like this:
1552 <IndexTerm><Primary>Makefile, minimal</Primary></IndexTerm>
1555 # Makefile for fptools project "small"
1558 include $(TOP)/mk/boilerplate.mk
1560 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1563 include $(TOP)/target.mk
1569 This <Filename>Makefile</Filename> has three sections:
1578 The first section includes
1582 One of the most important
1583 features of GNU <Command>make</Command> that we use is the ability for a <Filename>Makefile</Filename> to
1584 include another named file, very like <Command>cpp</Command>'s <Literal>#include</Literal>
1589 a file of ``boilerplate'' code from the level
1590 above (which in this case will be
1591 <Filename><Constant>FPTOOLS_TOP</Constant>/mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>). As its name
1592 suggests, <Filename>boilerplate.mk</Filename> consists of a large quantity of standard
1593 <Filename>Makefile</Filename> code. We discuss this boilerplate in more detail in
1594 <XRef LinkEnd="sec-boiler">.
1595 <IndexTerm><Primary>include, directive in Makefiles</Primary></IndexTerm>
1596 <IndexTerm><Primary>Makefile inclusion</Primary></IndexTerm>
1598 Before the <Literal>include</Literal> statement, you must define the <Command>make</Command> variable
1599 <Constant>TOP</Constant><IndexTerm><Primary>TOP</Primary></IndexTerm> to be the directory containing the <Filename>mk</Filename> directory in
1600 which the <Filename>boilerplate.mk</Filename> file is. It is <Emphasis>not</Emphasis> OK to simply say
1604 include ../mk/boilerplate.mk # NO NO NO
1608 Why? Because the <Filename>boilerplate.mk</Filename> file needs to know where it is, so
1609 that it can, in turn, <Literal>include</Literal> other files. (Unfortunately, when an
1610 <Literal>include</Literal>d file does an <Literal>include</Literal>, the filename is treated relative to
1611 the directory in which <Command>gmake</Command> is being run, not the directory in
1612 which the <Literal>include</Literal>d sits.) In general, <Emphasis>every file <Filename>foo.mk</Filename>
1613 assumes that <Filename><Constant>$(TOP)</Constant>/mk/foo.mk</Filename> refers to itself.</Emphasis> It is up to the
1614 <Filename>Makefile</Filename> doing the <Literal>include</Literal> to ensure this is the case.
1616 Files intended for inclusion in other <Filename>Makefile</Filename>s are written to have
1617 the following property: <Emphasis>after <Filename>foo.mk</Filename> is <Literal>include</Literal>d, it leaves
1618 <Constant>TOP</Constant> containing the same value as it had just before the <Literal>include</Literal>
1619 statement</Emphasis>. In our example, this invariant guarantees that the
1620 <Literal>include</Literal> for <Filename>target.mk</Filename> will look in the same directory as that for
1621 <Filename>boilerplate.mk</Filename>.
1628 The second section defines the following standard <Command>make</Command>
1629 variables: <Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm> (the source files from which is to be
1630 built), and <Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm> (the executable binary to be
1631 built). We will discuss in more detail what the ``standard
1632 variables'' are, and how they affect what happens, in <XRef LinkEnd="sec-targets">.
1634 The definition for <Constant>SRCS</Constant> uses the useful GNU <Command>make</Command> construct
1635 <Literal>$(wildcard $pat$)</Literal><IndexTerm><Primary>wildcard</Primary></IndexTerm>, which expands to a list of all
1636 the files matching the pattern <Literal>pat</Literal> in the current directory. In
1637 this example, <Constant>SRCS</Constant> is set to the list of all the <Filename>.lhs</Filename> and <Filename>.c</Filename>
1638 files in the directory. (Let's suppose there is one of each,
1639 <Filename>Foo.lhs</Filename> and <Filename>Baz.c</Filename>.)
1646 The last section includes a second file of standard code,
1647 called <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm>. It contains the rules that tell
1648 <Command>gmake</Command> how to make the standard targets (<Xref LinkEnd="sec-standard-targets">). Why, you ask,
1649 can't this standard code be part of <Filename>boilerplate.mk</Filename>? Good question.
1650 We discuss the reason later, in <Xref LinkEnd="sec-boiler-arch">.
1652 You do not <Emphasis>have</Emphasis> to <Literal>include</Literal> the <Filename>target.mk</Filename> file. Instead, you
1653 can write rules of your own for all the standard targets. Usually,
1654 though, you will find quite a big payoff from using the canned rules
1655 in <Filename>target.mk</Filename>; the price tag is that you have to understand what
1656 canned rules get enabled, and what they do (<Xref LinkEnd="sec-targets">).
1666 In our example <Filename>Makefile</Filename>, most of the work is done by the two
1667 <Literal>include</Literal>d files. When you say <Command>gmake all</Command>, the following things
1677 <Command>gmake</Command> figures out that the object files are <Filename>Foo.o</Filename> and
1678 <Filename>Baz.o</Filename>.
1685 It uses a boilerplate pattern rule to compile <Filename>Foo.lhs</Filename> to
1686 <Filename>Foo.o</Filename> using a Haskell compiler. (Which one? That is set in the
1687 build configuration.)
1694 It uses another standard pattern rule to compile <Filename>Baz.c</Filename> to
1695 <Filename>Baz.o</Filename>, using a C compiler. (Ditto.)
1702 It links the resulting <Filename>.o</Filename> files together to make <Literal>small</Literal>,
1703 using the Haskell compiler to do the link step. (Why not use <Command>ld</Command>?
1704 Because the Haskell compiler knows what standard libraries to link in.
1705 How did <Command>gmake</Command> know to use the Haskell compiler to do the link,
1706 rather than the C compiler? Because we set the variable <Constant>HS_PROG</Constant>
1707 rather than <Constant>C_PROG</Constant>.)
1717 All <Filename>Makefile</Filename>s should follow the above three-section format.
1723 <Title>A larger project</Title>
1726 Larger projects are usually structured into a number of sub-directories,
1727 each of which has its own <Filename>Makefile</Filename>. (In very large projects, this
1728 sub-structure might be iterated recursively, though that is rare.)
1729 To give you the idea, here's part of the directory structure for
1730 the (rather large) GHC project:
1743 ...source files for documentation...
1746 ...source files for driver...
1749 parser/...source files for parser...
1750 renamer/...source files for renamer...
1757 The sub-directories <Filename>docs</Filename>, <Filename>driver</Filename>, <Filename>compiler</Filename>, and so on, each
1758 contains a sub-component of GHC, and each has its own <Filename>Makefile</Filename>.
1759 There must also be a <Filename>Makefile</Filename> in <Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc</Filename>. It does most
1760 of its work by recursively invoking <Command>gmake</Command> on the <Filename>Makefile</Filename>s in the
1761 sub-directories. We say that <Filename>ghc/Makefile</Filename> is a <Emphasis>non-leaf
1762 <Filename>Makefile</Filename></Emphasis>, because it does little except organise its children,
1763 while the <Filename>Makefile</Filename>s in the sub-directories are all <Emphasis>leaf
1764 <Filename>Makefile</Filename>s</Emphasis>. (In principle the sub-directories might themselves
1765 contain a non-leaf <Filename>Makefile</Filename> and several sub-sub-directories, but
1766 that does not happen in GHC.)
1770 The <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename> is considered a leaf <Filename>Makefile</Filename> even
1771 though the <Filename>ghc/compiler</Filename> has sub-directories, because these sub-directories
1772 do not themselves have <Filename>Makefile</Filename>s in them. They are just used to structure
1773 the collection of modules that make up GHC, but all are managed by the
1774 single <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename>.
1778 You will notice that <Filename>ghc/</Filename> also contains a directory <Filename>ghc/mk/</Filename>. It
1779 contains GHC-specific <Filename>Makefile</Filename> boilerplate code. More precisely:
1788 <Filename>ghc/mk/boilerplate.mk</Filename> is included at the top of
1789 <Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the
1790 sub-directories. It in turn <Literal>include</Literal>s the main boilerplate file
1791 <Filename>mk/boilerplate.mk</Filename>.
1799 <Filename>ghc/mk/target.mk</Filename> is <Literal>include</Literal>d at the bottom of
1800 <Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the
1801 sub-directories. It in turn <Literal>include</Literal>s the file <Filename>mk/target.mk</Filename>.
1811 So these two files are the place to look for GHC-wide customisation
1812 of the standard boilerplate.
1817 <Sect2 id="sec-boiler-arch">
1818 <Title>Boilerplate architecture
1819 <IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm>
1823 Every <Filename>Makefile</Filename> includes a <Filename>boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> file
1824 at the top, and <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> file at the bottom. In
1825 this section we discuss what is in these files, and why there have to
1826 be two of them. In general:
1835 <Filename>boilerplate.mk</Filename> consists of:
1841 <Emphasis>Definitions of millions of <Command>make</Command> variables</Emphasis> that
1842 collectively specify the build configuration. Examples:
1843 <Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the options to feed to the Haskell compiler;
1844 <Constant>NoFibSubDirs</Constant><IndexTerm><Primary>NoFibSubDirs</Primary></IndexTerm>, the sub-directories to enable within the
1845 <Literal>nofib</Literal> project; <Constant>GhcWithHc</Constant><IndexTerm><Primary>GhcWithHc</Primary></IndexTerm>, the name of the Haskell
1846 compiler to use when compiling GHC in the <Literal>ghc</Literal> project.
1852 <Emphasis>Standard pattern rules</Emphasis> that tell <Command>gmake</Command> how to construct one
1860 <Filename>boilerplate.mk</Filename> needs to be <Literal>include</Literal>d at the <Emphasis>top</Emphasis>
1861 of each <Filename>Makefile</Filename>, so that the user can replace the
1862 boilerplate definitions or pattern rules by simply giving a new
1863 definition or pattern rule in the <Filename>Makefile</Filename>. <Command>gmake</Command>
1864 simply takes the last definition as the definitive one.
1866 Instead of <Emphasis>replacing</Emphasis> boilerplate definitions, it is also quite
1867 common to <Emphasis>augment</Emphasis> them. For example, a <Filename>Makefile</Filename> might say:
1875 thereby adding ``<Option>-O</Option>'' to the end of <Constant>SRC_HC_OPTS</Constant><IndexTerm><Primary>SRC_HC_OPTS</Primary></IndexTerm>.
1882 <Filename>target.mk</Filename> contains <Command>make</Command> rules for the standard
1883 targets described in <Xref LinkEnd="sec-standard-targets">. These rules are selectively included,
1884 depending on the setting of certain <Command>make</Command> variables. These
1885 variables are usually set in the middle section of the
1886 <Filename>Makefile</Filename> between the two <Literal>include</Literal>s.
1888 <Filename>target.mk</Filename> must be included at the end (rather than being part of
1889 <Filename>boilerplate.mk</Filename>) for several tiresome reasons:
1896 <Command>gmake</Command> commits target and dependency lists earlier than
1897 it should. For example, <FIlename>target.mk</FIlename> has a rule that looks like
1902 $(HS_PROG) : $(OBJS)
1903 $(HC) $(LD_OPTS) $< -o $@
1907 If this rule was in <Filename>boilerplate.mk</Filename> then <Constant>$(HS_PROG)</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>
1908 and <Constant>$(OBJS)</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm> would not have their final values at the
1909 moment <Command>gmake</Command> encountered the rule. Alas, <Command>gmake</Command> takes a snapshot
1910 of their current values, and wires that snapshot into the rule. (In
1911 contrast, the commands executed when the rule ``fires'' are only
1912 substituted at the moment of firing.) So, the rule must follow the
1913 definitions given in the <Filename>Makefile</Filename> itself.
1920 Unlike pattern rules, ordinary rules cannot be overriden or
1921 replaced by subsequent rules for the same target (at least, not without an
1922 error message). Including ordinary rules in <Filename>boilerplate.mk</Filename> would
1923 prevent the user from writing rules for specific targets in specific cases.
1930 There are a couple of other reasons I've forgotten, but it doesn't
1946 <Sect2 id="sec-boiler">
1947 <Title>The main <Filename>mk/boilerplate.mk</Filename> file
1949 <IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm></Title>
1952 If you look at <Filename><Constant>$(FPTOOLS_TOP)</Constant>/mk/boilerplate.mk</Filename> you will find
1953 that it consists of the following sections, each held in a separate
1961 <Term><Filename>config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm></Term>
1964 is the build configuration file we
1965 discussed at length in <Xref LinkEnd="sec-build-config">.
1967 </ListItem></VarListEntry>
1969 <Term><Filename>paths.mk</Filename><IndexTerm><Primary>paths.mk</Primary></IndexTerm></Term>
1972 defines <Command>make</Command> variables for
1973 pathnames and file lists. In particular, it gives definitions for:
1980 <Term><Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm>:</Term>
1983 all source files in the current directory.
1985 </ListItem></VarListEntry>
1987 <Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>:</Term>
1990 all Haskell source files in the current directory.
1991 It is derived from <Constant>$(SRCS)</Constant>, so if you override <Constant>SRCS</Constant> with a new value
1992 <Constant>HS_SRCS</Constant> will follow suit.
1994 </ListItem></VarListEntry>
1996 <Term><Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>:</Term>
1999 similarly for C source files.
2001 </ListItem></VarListEntry>
2003 <Term><Constant>HS_OBJS</Constant><IndexTerm><Primary>HS_OBJS</Primary></IndexTerm>:</Term>
2006 the <Filename>.o</Filename> files derived from <Constant>$(HS_SRCS)</Constant>.
2008 </ListItem></VarListEntry>
2010 <Term><Constant>C_OBJS</Constant><IndexTerm><Primary>C_OBJS</Primary></IndexTerm>:</Term>
2013 similarly for <Constant>$(C_SRCS)</Constant>.
2015 </ListItem></VarListEntry>
2017 <Term><Constant>OBJS</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm>:</Term>
2020 the concatenation of <Constant>$(HS_OBJS)</Constant> and <Constant>$(C_OBJS)</Constant>.
2022 </ListItem></VarListEntry>
2027 Any or all of these definitions can easily be overriden by giving new
2028 definitions in your <Filename>Makefile</Filename>. For example, if there are things in
2029 the current directory that look like source files but aren't, then
2030 you'll need to set <Constant>SRCS</Constant> manually in your <Filename>Makefile</Filename>. The other
2031 definitions will then work from this new definition.
2035 What, exactly, does <Filename>paths.mk</Filename> consider a ``source file'' to be? It's
2036 based on the file's suffix (e.g. <Filename>.hs</Filename>, <Filename>.lhs</Filename>, <Filename>.c</Filename>, <Filename>.lc</Filename>, etc), but
2037 this is the kind of detail that changes, so rather than
2038 enumerate the source suffices here the best thing to do is to look in
2039 <Filename>paths.mk</Filename>.
2041 </ListItem></VarListEntry>
2043 <Term><Filename>opts.mk</Filename><IndexTerm><Primary>opts.mk</Primary></IndexTerm></Term>
2046 defines <Command>make</Command> variables for option
2047 strings to pass to each program. For example, it defines
2048 <Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the option strings to pass to the Haskell
2049 compiler. See <Xref LinkEnd="sec-suffix">.
2051 </ListItem></VarListEntry>
2053 <Term><Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm></Term>
2056 defines standard pattern rules—see <Xref LinkEnd="sec-suffix">.
2058 </ListItem></VarListEntry>
2063 Any of the variables and pattern rules defined by the boilerplate file
2064 can easily be overridden in any particular <Filename>Makefile</Filename>, because the
2065 boilerplate <Literal>include</Literal> comes first. Definitions after this <Literal>include</Literal>
2066 directive simply override the default ones in <Filename>boilerplate.mk</Filename>.
2071 <Sect2 id="sec-suffix">
2072 <Title>Pattern rules and options
2074 <IndexTerm><Primary>Pattern rules</Primary></IndexTerm></Title>
2077 The file <Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm> defines standard <Emphasis>pattern
2078 rules</Emphasis> that say how to build one kind of file from another, for
2079 example, how to build a <Filename>.o</Filename> file from a <Filename>.c</Filename> file. (GNU <Command>make</Command>'s
2080 <Emphasis>pattern rules</Emphasis> are more powerful and easier to use than Unix
2081 <Command>make</Command>'s <Emphasis>suffix rules</Emphasis>.)
2085 Almost all the rules look something like this:
2093 $(CC) $(CC_OPTS) -c $< -o $@
2099 Here's how to understand the rule. It says that
2100 <Emphasis>something</Emphasis><Filename>.o</Filename> (say <Filename>Foo.o</Filename>) can be built from
2101 <Emphasis>something</Emphasis><Filename>.c</Filename> (<Filename>Foo.c</Filename>), by invoking the C compiler
2102 (path name held in <Constant>$(CC)</Constant>), passing to it the options
2103 <Constant>$(CC_OPTS)</Constant> and the rule's dependent file of the rule
2104 <Literal>$<</Literal> (<Filename>Foo.c</Filename> in this case), and putting the result in
2105 the rule's target <Literal>$@</Literal> (<Filename>Foo.o</Filename> in this case).
2109 Every program is held in a <Command>make</Command> variable defined in
2110 <Filename>mk/config.mk</Filename>—look in <Filename>mk/config.mk</Filename> for the
2111 complete list. One important one is the Haskell compiler, which is
2112 called <Constant>$(HC)</Constant>.
2116 Every program's options are are held in a <Command>make</Command> variables called
2117 <Constant><prog>_OPTS</Constant>. the <Constant><prog>_OPTS</Constant> variables are defined in
2118 <Filename>mk/opts.mk</Filename>. Almost all of them are defined like this:
2124 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
2130 The four variables from which <Constant>CC_OPTS</Constant> is built have the following meaning:
2137 <Term><Constant>SRC_CC_OPTS</Constant><IndexTerm><Primary>SRC_CC_OPTS</Primary></IndexTerm>:</Term>
2140 options passed to all C
2143 </ListItem></VarListEntry>
2145 <Term><Constant>WAY_<way>_CC_OPTS</Constant>:</Term>
2149 compilations for way <Literal><way></Literal>. For example,
2150 <Constant>WAY_mp_CC_OPTS</Constant> gives options to pass to the C compiler when
2151 compiling way <Literal>mp</Literal>. The variable <Constant>WAY_CC_OPTS</Constant> holds
2152 options to pass to the C compiler when compiling the standard way.
2153 (<Xref LinkEnd="sec-ways"> dicusses multi-way
2156 </ListItem></VarListEntry>
2158 <Term><Constant><module>_CC_OPTS</Constant>:</Term>
2162 pass to the C compiler that are specific to module <Literal><module></Literal>. For example, <Constant>SMap_CC_OPTS</Constant> gives the specific options
2163 to pass to the C compiler when compiling <Filename>SMap.c</Filename>.
2165 </ListItem></VarListEntry>
2167 <Term><Constant>EXTRA_CC_OPTS</Constant><IndexTerm><Primary>EXTRA_CC_OPTS</Primary></IndexTerm>:</Term>
2170 extra options to pass to all
2171 C compilations. This is intended for command line use, thus:
2177 gmake libHS.a EXTRA_CC_OPTS="-v"
2181 </ListItem></VarListEntry>
2187 <Sect2 id="sec-targets">
2188 <Title>The main <Filename>mk/target.mk</Filename> file
2190 <IndexTerm><Primary>target.mk</Primary></IndexTerm></Title>
2193 <Filename>target.mk</Filename> contains canned rules for all the standard targets
2194 described in <Xref LinkEnd="sec-standard-targets">. It is complicated by the fact that you don't want all of
2195 these rules to be active in every <Filename>Makefile</Filename>. Rather than have a
2196 plethora of tiny files which you can include selectively, there is a
2197 single file, <Filename>target.mk</Filename>, which selectively includes rules based on
2198 whether you have defined certain variables in your <Filename>Makefile</Filename>. This
2199 section explains what rules you get, what variables control them, and
2200 what the rules do. Hopefully, you will also get enough of an idea of
2201 what is supposed to happen that you can read and understand any weird
2202 special cases yourself.
2209 <Term><Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>.</Term>
2212 If <Constant>HS_PROG</Constant> is defined, you get
2213 rules with the following targets:
2217 <Term><Filename>HS_PROG</Filename><IndexTerm><Primary>HS_PROG</Primary></IndexTerm></Term>
2220 itself. This rule links <Constant>$(OBJS)</Constant>
2221 with the Haskell runtime system to get an executable called
2222 <Constant>$(HS_PROG)</Constant>.
2224 </ListItem></VarListEntry>
2226 <Term><Literal>install</Literal><IndexTerm><Primary>install</Primary></IndexTerm></Term>
2229 installs <Constant>$(HS_PROG)</Constant>
2230 in <Constant>$(bindir)</Constant>.
2232 </ListItem></VarListEntry>
2235 </ListItem></VarListEntry>
2237 <Term><Constant>C_PROG</Constant><IndexTerm><Primary>C_PROG</Primary></IndexTerm></Term>
2240 is similar to <Constant>HS_PROG</Constant>, except that
2241 the link step links <Constant>$(C_OBJS)</Constant> with the C runtime system.
2243 </ListItem></VarListEntry>
2245 <Term><Constant>LIBRARY</Constant><IndexTerm><Primary>LIBRARY</Primary></IndexTerm></Term>
2248 is similar to <Constant>HS_PROG</Constant>, except that
2249 it links <Constant>$(LIB_OBJS)</Constant> to make the library archive <Constant>$(LIBRARY)</Constant>, and
2250 <Literal>install</Literal> installs it in <Constant>$(libdir)</Constant>.
2252 </ListItem></VarListEntry>
2254 <Term><Constant>LIB_DATA</Constant><IndexTerm><Primary>LIB_DATA</Primary></IndexTerm></Term>
2259 </ListItem></VarListEntry>
2261 <Term><Constant>LIB_EXEC</Constant><IndexTerm><Primary>LIB_EXEC</Primary></IndexTerm></Term>
2266 </ListItem></VarListEntry>
2268 <Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>, <Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>.</Term>
2271 If <Constant>HS_SRCS</Constant>
2272 is defined and non-empty, a rule for the target <Literal>depend</Literal> is included,
2273 which generates dependency information for Haskell programs.
2274 Similarly for <Constant>C_SRCS</Constant>.
2276 </ListItem></VarListEntry>
2281 All of these rules are ``double-colon'' rules, thus
2287 install :: $(HS_PROG)
2288 ...how to install it...
2294 GNU <Command>make</Command> treats double-colon rules as separate entities. If there
2295 are several double-colon rules for the same target it takes each in
2296 turn and fires it if its dependencies say to do so. This means that
2297 you can, for example, define both <Constant>HS_PROG</Constant> and <Constant>LIBRARY</Constant>, which will
2298 generate two rules for <Literal>install</Literal>. When you type <Command>gmake install</Command> both
2299 rules will be fired, and both the program and the library will be
2300 installed, just as you wanted.
2305 <Sect2 id="sec-subdirs">
2308 <IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm>
2309 <IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm></Title>
2312 In leaf <Filename>Makefile</Filename>s the variable <Constant>SUBDIRS</Constant><IndexTerm><Primary>SUBDIRS</Primary></IndexTerm> is undefined.
2313 In non-leaf <Filename>Makefile</Filename>s, <Constant>SUBDIRS</Constant> is set to the list of
2314 sub-directories that contain subordinate <Filename>Makefile</Filename>s. <Emphasis>It is up to
2315 you to set <Constant>SUBDIRS</Constant> in the <Filename>Makefile</Filename>.</Emphasis> There is no automation here—<Constant>SUBDIRS</Constant> is too important to automate.
2319 When <Constant>SUBDIRS</Constant> is defined, <Filename>target.mk</Filename> includes a rather
2320 neat rule for the standard targets (<Xref LinkEnd="sec-standard-targets"> that simply invokes
2321 <Command>make</Command> recursively in each of the sub-directories.
2325 <Emphasis>These recursive invocations are guaranteed to occur in the order
2326 in which the list of directories is specified in <Constant>SUBDIRS</Constant>. </Emphasis>This
2327 guarantee can be important. For example, when you say <Command>gmake boot</Command> it
2328 can be important that the recursive invocation of <Command>make boot</Command> is done
2329 in one sub-directory (the include files, say) before another (the
2330 source files). Generally, put the most independent sub-directory
2331 first, and the most dependent last.
2336 <Sect2 id="sec-ways">
2337 <Title>Way management
2339 <IndexTerm><Primary>way management</Primary></IndexTerm></Title>
2342 We sometimes want to build essentially the same system in several
2343 different ``ways''. For example, we want to build GHC's <Literal>Prelude</Literal>
2344 libraries with and without profiling, with and without concurrency,
2345 and so on, so that there is an appropriately-built library archive to
2346 link with when the user compiles his program. It would be possible to
2347 have a completely separate build tree for each such ``way'', but it
2348 would be horribly bureaucratic, especially since often only parts of
2349 the build tree need to be constructed in multiple ways.
2353 Instead, the <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> contains some clever magic to
2354 allow you to build several versions of a system; and to control
2355 locally how many versions are built and how they differ. This section
2360 The files for a particular way are distinguished by munging the
2361 suffix. The ``normal way'' is always built, and its files have the
2362 standard suffices <Filename>.o</Filename>, <Filename>.hi</Filename>, and so on. In addition, you can build
2363 one or more extra ways, each distinguished by a <Emphasis>way tag</Emphasis>. The
2364 object files and interface files for one of these extra ways are
2365 distinguished by their suffix. For example, way <Literal>mp</Literal> has files
2366 <Filename>.mp_o</Filename> and <Filename>.mp_hi</Filename>. Library archives have their way tag the other
2367 side of the dot, for boring reasons; thus, <Filename>libHS_mp.a</Filename>.
2371 A <Command>make</Command> variable called <Constant>way</Constant> holds the current way tag. <Emphasis><Constant>way</Constant>
2372 is only ever set on the command line of a recursive invocation of
2373 <Command>gmake</Command>.</Emphasis> It is never set inside a <Filename>Makefile</Filename>. So it is a global
2374 constant for any one invocation of <Command>gmake</Command>. Two other <Command>make</Command>
2375 variables, <Constant>way_</Constant> and <Constant>_way</Constant> are immediately derived from <Constant>$(way)</Constant> and
2376 never altered. If <Constant>way</Constant> is not set, then neither are <Constant>way_</Constant> and
2377 <Constant>_way</Constant>, and the invocation of <Command>make</Command> will build the ``normal way''.
2378 If <Constant>way</Constant> is set, then the other two variables are set in sympathy.
2379 For example, if <Constant>$(way)</Constant> is ``<Literal>mp</Literal>'', then <Constant>way_</Constant> is set to ``<Literal>mp_</Literal>''
2380 and <Constant>_way</Constant> is set to ``<Literal>_mp</Literal>''. These three variables are then used
2381 when constructing file names.
2385 So how does <Command>make</Command> ever get recursively invoked with <Constant>way</Constant> set? There
2386 are two ways in which this happens:
2395 For some (but not all) of the standard targets, when in a leaf
2396 sub-directory, <Command>make</Command> is recursively invoked for each way tag in
2397 <Constant>$(WAYS)</Constant>. You set <Constant>WAYS</Constant> to the list of way tags you want these
2398 targets built for. The mechanism here is very much like the recursive
2399 invocation of <Command>make</Command> in sub-directories (<Xref LinkEnd="sec-subdirs">).
2401 It is up to you to set <Constant>WAYS</Constant> in your <Filename>Makefile</Filename>; this is how you
2402 control what ways will get built.
2408 For a useful collection of
2409 targets (such as <Filename>libHS_mp.a</Filename>, <Filename>Foo.mp_o</Filename>) there is a rule which
2410 recursively invokes <Command>make</Command> to make the specified target, setting the
2411 <Constant>way</Constant> variable. So if you say <Command>gmake Foo.mp_o</Command> you should see a
2412 recursive invocation <Command>gmake Foo.mp_o way=mp</Command>, and <Emphasis>in this
2413 recursive invocation the pattern rule for compiling a Haskell file
2414 into a <Filename>.o</Filename> file will match</Emphasis>. The key pattern rules (in <Filename>suffix.mk</Filename>)
2420 $(HC) $(HC_OPTS) $< -o $@
2435 <Title>When the canned rule isn't right</Title>
2438 Sometimes the canned rule just doesn't do the right thing. For
2439 example, in the <Literal>nofib</Literal> suite we want the link step to print out
2440 timing information. The thing to do here is <Emphasis>not</Emphasis> to define
2441 <Constant>HS_PROG</Constant> or <Constant>C_PROG</Constant>, and instead define a special purpose rule in
2442 your own <Filename>Makefile</Filename>. By using different variable names you will avoid
2443 the canned rules being included, and conflicting with yours.
2450 <Sect1 id="sec-booting-from-C">
2451 <Title>Booting/porting from C (<Filename>.hc</Filename>) files
2453 <IndexTerm><Primary>building GHC from .hc files</Primary></IndexTerm>
2454 <IndexTerm><Primary>booting GHC from .hc files</Primary></IndexTerm>
2455 <IndexTerm><Primary>porting GHC</Primary></IndexTerm></Title>
2458 This section is for people trying to get GHC going by using the
2459 supplied intermediate C (<Filename>.hc</Filename>) files. This would probably be because
2460 no binaries have been provided, or because the machine is not ``fully
2465 The intermediate C files are normally made available together with a
2466 source release, please check the announce message for exact directions
2467 of where to find them. If we haven't made them available or you
2468 can't find them, please ask.
2472 Assuming you've got them, unpack them on top of a fresh source tree.
2473 Then follow the `normal' instructions in <Xref LinkEnd="sec-building-from-source"> for setting
2474 up a build tree. When you invoke the configure script, you'll have
2475 to tell the script about your intentions:
2481 foo% ./configure --enable-hc-boot
2484 <IndexTerm><Primary>--enable-hc-boot</Primary></IndexTerm>
2485 <IndexTerm><Primary>--disable-hc-boot</Primary></IndexTerm>
2489 Assuming it configures OK and you don't need to create <Filename>mk/build.mk</Filename>
2490 for any other purposes, the next step is to proceed with a <Command>make boot</Command>
2491 followed by <Command>make all</Command>. At the successful completion of <Command>make all</Command>,
2492 you should end up with a binary of the compiler proper,
2493 <Filename>ghc/compiler/hsc</Filename>, plus archives (but no <Filename>.hi</Filename> files!) of the prelude
2494 libraries. To generate the Prelude interface files (and test drive the
2495 bootstrapped compiler), re-run the <Command>configure</Command> script, but this time
2496 without the <Option>--enable-hc-boot</Option> option. After that re-create the
2497 contents of <Filename>ghc/lib</Filename>:
2514 That's the mechanics of the boot process, but, of course, if you're
2515 trying to boot on a platform that is not supported and significantly
2516 `different' from any of the supported ones, this is only the start of
2517 the adventure…(ToDo: porting tips—stuff to look out for, etc.)
2522 <Sect1 id="sec-build-pitfalls">
2523 <Title>Known pitfalls in building Glasgow Haskell
2525 <IndexTerm><Primary>problems, building</Primary></IndexTerm>
2526 <IndexTerm><Primary>pitfalls, in building</Primary></IndexTerm>
2527 <IndexTerm><Primary>building pitfalls</Primary></IndexTerm></Title>
2530 WARNINGS about pitfalls and known ``problems'':
2539 One difficulty that comes up from time to time is running out of space
2540 in <Filename>/tmp</Filename>. (It is impossible for the configuration stuff to
2541 compensate for the vagaries of different sysadmin approaches to temp
2543 <IndexTerm><Primary>tmp, running out of space in</Primary></IndexTerm>
2545 The quickest way around it is <Command>setenv TMPDIR /usr/tmp</Command><IndexTerm><Primary>TMPDIR</Primary></IndexTerm> or
2546 even <Command>setenv TMPDIR .</Command> (or the equivalent incantation with your shell
2549 The best way around it is to say
2552 export TMPDIR=<dir>
2555 in your <Filename>build.mk</Filename> file.
2556 Then GHC and the other <Literal>fptools</Literal> programs will use the appropriate directory
2565 In compiling some support-code bits, e.g., in <Filename>ghc/rts/gmp</Filename> and even
2566 in <Filename>ghc/lib</Filename>, you may get a few C-compiler warnings. We think these
2574 When compiling via C, you'll sometimes get ``warning: assignment from
2575 incompatible pointer type'' out of GCC. Harmless.
2582 Similarly, <Command>ar</Command>chiving warning messages like the following are not
2586 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
2587 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
2597 In compiling the compiler proper (in <Filename>compiler/</Filename>), you <Emphasis>may</Emphasis>
2598 get an ``Out of heap space'' error message. These can vary with the
2599 vagaries of different systems, it seems. The solution is simple:
2606 If you're compiling with GHC 4.00 or above, then the
2607 <Emphasis>maximum</Emphasis> heap size must have been reached. This is somewhat
2608 unlikely, since the maximum is set to 64M by default. Anyway, you can
2609 raise it with the <Option>-optCrts-M<size></Option> flag (add this flag to
2610 <Constant><module>_HC_OPTS</Constant> <Command>make</Command> variable in the appropriate <Filename>Makefile</Filename>).
2617 For GHC < 4.00, add a suitable <Option>-H</Option> flag to the <Filename>Makefile</Filename>, as
2626 and try again: <Command>gmake</Command>. (see <Xref LinkEnd="sec-suffix"> for information about
2627 <Constant><module>_HC_OPTS</Constant>.)
2629 Alternatively, just cut to the chase:
2633 % make EXTRA_HC_OPTS=-optCrts-M128M
2642 If you try to compile some Haskell, and you get errors from GCC about
2643 lots of things from <Filename>/usr/include/math.h</Filename>, then your GCC was
2644 mis-installed. <Command>fixincludes</Command> wasn't run when it should've been.
2646 As <Command>fixincludes</Command> is now automagically run as part of GCC installation,
2647 this bug also suggests that you have an old GCC.
2655 You <Emphasis>may</Emphasis> need to re-<Command>ranlib</Command><IndexTerm><Primary>ranlib</Primary></IndexTerm> your libraries (on Sun4s).
2659 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
2660 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
2662 ? # or, on some machines: ar s $i
2667 We'd be interested to know if this is still necessary.
2675 GHC's sources go through <Command>cpp</Command> before being compiled, and <Command>cpp</Command> varies
2676 a bit from one Unix to another. One particular gotcha is macro calls
2681 SLIT("Hello, world")
2685 Some <Command>cpp</Command>s treat the comma inside the string as separating two macro
2686 arguments, so you get
2690 :731: macro `SLIT' used with too many (2) args
2694 Alas, <Command>cpp</Command> doesn't tell you the offending file!
2696 Workaround: don't put weird things in string args to <Command>cpp</Command> macros.
2707 <Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
2710 This section summarises how to get the utilities you need on your
2711 Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. It is based largely on detailed advice from Sigbjørn Finne.
2715 <Sect2><Title>Installing ssh</Title>
2721 Extract the whole of <ULink URL="http://research.microsoft.com/~simonpj/ssh-1_2_26-cygwinb19.tar.gz">the ssh archive</ULink> into your <Filename>C:\</Filename> directory, and use the ``All files'' and ``User folder names'' options in WinZip extract dialogue box. This populates your <Filename>C:\usr\local</Filename> tree.
2727 Extract <ULink URL="http://research.microsoft.com/~simonpj/cygwinb19.dll.zip">cygwinb19.dll</ULink> into <Filename>/usr/local/bin</Filename>. The current version
2728 of Cywin is b20, but this version of ssh was compiled with b19.
2734 On a Win2k machine, open up a bash and do
2739 foo$ mkpasswd -l > passwd
2743 Check that your login entry is on the first line
2744 of that file. If not, move it to the top. It's OK
2745 for 'Administrator' to be the first entry, assuming you are one.
2749 However, Win9x doesn't support the calls that <Command>mkpasswd</Command> relies on
2750 (e.g., <Function>NetUserEnum</Function>). If you run <Command>mkpasswd</Command> you
2755 linked to missing export netapi32.dll:NetUserEnum
2759 The passwd file is used
2760 by ssh in a fairly rudimentary manner, so I'd simply
2761 synthesise/copy an existing Unix <Filename>/etc/passwd</Filename>, i.e., create
2762 an <Filename>/etc/passwd</Filename> file containing the line
2766 <login>::500:513:::/bin/sh
2770 where <Literal><login></Literal> is your login id.
2776 Generate a key, by running <Filename>c:/user/local/bin/ssh-keygen1</Filename>.
2777 This generates a public key in <Filename>.ssh/identity.pub</Filename>, and a
2778 private key in <Filename>.ssh/identity</Filename>
2782 In response to the 'Enter passphrase' question, just hit
2783 return (i.e. use an empty passphrase). The passphrase is
2784 a password that protects your private key. But it's a pain
2785 to type this passphrase everytime you use <Command>ssh</Command>, so the best
2786 thing to do is simply to protect your <Filename>.ssh</Filename> directory, and
2787 <Filename>.ssh/identity</Filename> from access by anyone else. To do this
2788 right-click your <Filename>.ssh</Filename> directory, and select Properties.
2789 If you are not on the access control list, add yourself, and
2790 give yourself full permissions (the second panel).
2791 Remove everyone else from the access control list. (Don't
2792 leave them there but deny them access, because 'they' may be
2793 a list that includes you!)
2797 If you have problems running <Command>ssh-keygen1</Command>
2798 from within <Command>bash</Command>, start up <Filename>cmd.exe</Filename> and run it as follows:
2802 c:\tmp> set CYGWIN32=tty
2803 c:\tmp> c:/user/local/bin/ssh-keygen1
2809 If you don't have an account on <Literal>cvs.haskell.org</Literal>, send
2810 your <Filename>.ssh/identity.pub</Filename> to the CVS repository administrator
2811 (currently Jeff Lewis <Email>jlewis@cse.ogi.edu</Email>). He will set up
2816 If you do have an account on <Literal>cvs.haskell.org</Literal>, use TeraTerm
2817 to logon to it. Once in, copy the
2818 key that <Command>ssh-keygen1</Command> deposited in <Filename>/.ssh/identity.pub</Filename> into
2819 your <Filename>~/.ssh/authorized_keys</Filename>. Make sure that the new version
2820 of <Filename>authorized_keys</Filename> still has 600 file permission.
2829 <Sect2><Title>Installing CVS</Title>
2836 <ULink URL="http://research.microsoft.com/~simonpj/cvs-1_10-win.zip">
2837 CVS</ULink> and, following the instructions in the <Filename>README</Filename>, copy the
2838 appropriate files into <Filename>/usr/local/bin</Filename>.
2844 From the System control panel,
2845 set the following <Emphasis>user</Emphasis> environment variables (see the GHC user guide)
2851 <Constant>HOME</Constant>: points to your home directory. This is where CVS
2852 will look for its <Filename>.cvsrc</Filename> file.
2858 <Constant>CVS_RSH</Constant>: <Filename>c:/usr/local/bin/ssh1</Filename>
2864 <Constant>CVSROOT</Constant>: <Literal>:ext:username@cvs.haskell.org:/home/cvs/root</Literal>,
2865 where <Literal>username</Literal> is your userid
2871 <Constant>CVSEDITOR</Constant>: <Filename>bin/gnuclient.exe</Filename> if you want to use an Emacs buffer for typing in those long commit messages.
2879 Put the following in <Filename>$HOME/.cvsrc</Filename>:
2890 These are the default options for the specified CVS commands,
2891 and represent better defaults than the usual ones. (Feel
2892 free to change them.)
2896 Filenames starting with "<Filename>.</Filename>" were illegal in
2897 the 8.3 DOS filesystem, but that restriction should have
2898 been lifted by now (i.e., you're using VFAT or later filesystems.) If
2899 you're still having problems creating it, don't worry; <Filename>.cvsrc</Filename> is entirely
2906 Try doing <Command>cvs co fpconfig</Command>. All being well, bytes should
2907 start to trickle through, leaving a directory <Filename>fptools</Filename>
2908 in your current directory. (You can <Command>rm</Command> it if you don't want to keep it.) The following messages appear to be harmless:
2912 setsockopt IPTOS_LOWDELAY: Invalid argument
2913 setsockopt IPTOS_THROUGHPUT: Invalid argument
2917 At this point I found that CVS tried to invoke a little dialogue with
2918 me (along the lines of `do you want to talk to this host'), but
2919 somehow bombed out. This was from a bash shell running in emacs.
2920 I solved this by invoking a Cygnus shell, and running CVS from there.
2921 Once things are dialogue free, it seems to work OK from within emacs.
2927 If you want to check out part of large tree, proceed as follows:
2931 cvs -f checkout -l papers
2937 This sequence checks out the <Literal>papers</Literal> module, but none
2938 of its sub-directories.
2939 The "<Option>-l</Option>" flag says not to check out sub-directories.
2940 The "<Option>-f</Option>" flag says not to read the <Filename>.cvsrc</Filename> file
2941 whose <Option>-P</Option> default (don't check out empty directories) is
2946 The <Command>cvs update</Command> command sucks in a named sub-directory.
2953 There is a very nice graphical front-end to CVS for Win32 platforms,
2954 with a UI that people will be familiar with, at
2955 <ULink URL="http://www.wincvs.org/">wincvs.org</ULink>.
2956 I have not tried it yet.
2962 <Sect2><Title>Installing autoconf</Title>
2965 Only required if you are doing builds from GHC's sources
2966 checked out from the CVS tree.
2972 Fetch the (standard, Unix) <Command>autoconf</Command> distribution from
2973 <ULink URL="ftp://ftp.gnu.org/gnu/autoconf">ftp.gnu.org</ULink>.
2978 Unpack it into an arbitrary directory.
2983 Make sure that the directory <Filename>/usr/local/bin</Filename> exists.
2988 Say "<Filename>./configure</Filename>".
2993 Now <Command>make install</Command>. This should put <Filename>autoheader</Filename>
2994 and <Filename>autoconf</Filename> in <Filename>/usr/local/bin</Filename>.
3000 <Command>autoheader</Command> doesn't seem to work, but you don't need it
3007 <Sect2><Title>Building GHC</Title>
3013 In the <Filename>./configure</Filename> output, ignore
3015 checking whether #! works in shell scripts...
3016 ./configure: ./conftest: No such file or directory</Literal>",
3017 and "<Literal>not updating unwritable cache ./config.cache</Literal>".
3018 Nobody knows why these happen, but they seem to be harmless.
3024 You have to run <Command>autoconf</Command> both in <Filename>fptools</Filename>
3025 and in <Filename>fptools/ghc</Filename>. If you omit the latter step you'll
3026 get an error when you run <Filename>./configure</Filename>:
3031 creating mk/config.h
3032 mk/config.h is unchanged
3034 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
3035 ./configure: ./configure: No such file or directory
3036 configure: error: ./configure failed for ghc
3042 You need <Filename>ghc</Filename> to be in your <Constant>PATH</Constant> before you run
3043 <Command>configure</Command>. The default GHC InstallShield creates only
3044 <Filename>ghc-4.05</Filename>, so you may need to duplicate this file as <Filename>ghc</Filename>
3045 in the same directory, in order that <Command>configure</Command> will see it (or
3046 just rename <Filename>ghc-4.05</Filename> to <Filename>ghc</Filename>.
3047 And make sure that the directory is in your path.
3053 Compile <Command>happy</Command> and <Command>ghc</Command>
3054 with <Option>-static</Option>. To do this, set
3063 in your <Filename>build.mk</Filename> file.
3064 [Actually, I successfully compiled Happy without <Option>-static</Option> on Win2k, but not GHC.]
projects / ghc-hetmet.git / blob