1 <!doctype linuxdoc system>
4 <title>Building and Installing the Glasgow Functional Programming Tools Suite
7 Department of Computing Science,
12 Email: @glasgow-haskell-{users,bugs}@@dcs.gla.ac.uk@
13 <date>April 1998</date>
17 This guide is intended for people who want to install or modify
18 programs from the Glasgow @fptools@ suite (as distinct from those
19 who merely want to <em/run/ them).
25 <sect>Getting the Glasgow @fptools@ suite
26 <label id="sec:getting">
29 Building the Glasgow tools <em/can/ be complicated, mostly because
30 there are so many permutations of what/why/how, e.g., ``Build Happy
31 with HBC, everything else with GHC, leave out profiling, and test it
32 all on the `real' NoFib programs.'' Yeeps!
34 Happily, such complications don't apply to most people. A few common
35 ``strategies'' serve most purposes. Pick one and proceed
40 <tag><idx>Binary distribution</idx>.</tag>
41 If your only purpose is to install some of the @fptools@ suite
42 then the easiest thing to do is to get a binary distribution. In the
43 binary distribution everything is pre-compiled for your particular
44 machine architecture and operating system, so all you should have to
45 do is install the binaries and libraries in suitable places. Section
46 <ref id="sec:installing-bin-distrib" name="Installing a Binary
47 Distribution"> describes how to do this.
49 A binary distribution may not work for you for two reasons. First, we
50 may not have built the suite for the particular architecture/OS
51 platform you want. That may be due to lack of time and energy (in
52 which case you can get a source distribution and build from it; see
53 below). Alternatively, it may be because we haven't yet ported the
54 suite to your architecture, in which case you are considerably worse
57 The second reason a binary distribution may not be what you want is
58 if you want to read or modify the souce code.
60 <tag><idx>Source distribution</idx>.</tag> You have a supported
61 platform, but (a)~you like the warm fuzzy feeling of compiling things
62 yourself; (b)~you want to build something ``extra''---e.g., a set of
63 libraries with strictness-analysis turned off; or (c)~you want to hack
66 A source distribution contains complete sources for one or more
67 projects in the @fptools@ suite. Not only that, but the more awkward
68 machine-independent steps are done for you. For example, if you don't
69 have @flex@<ncdx/flex/ you'll find it convenient that the source
70 distribution contains the result of running @flex@ on the lexical
71 analyser specification. If you don't want to alter the lexical
72 analyser then this saves you having to find and install @flex@. You
73 will still need a working version of GHC on your machine in order to
74 compile (most of) the sources, however.
76 We make source distributions more frequently than binary
77 distributions; a release that comes with pre-compiled binaries
78 is considered a major release, i.e., a release that we have some
79 confidence will work well by having tested it (more) thoroughly.
81 Source-only distributions are either bugfix releases or snapshots of
82 current state of development. The release has undergone some testing.
83 Source releases of 4.xx can be compiled up using 2.10 or later.
85 <tag/Build GHC from intermediate C @.hc@ files<nidx/hc files/:/ You
86 need a working GHC to use a source distribution. What if you don't
87 have a working GHC? Then you have no choice but to ``bootstrap'' up
88 from the intermediate C (@.hc@) files that we provide. Building GHC
89 on an unsupported platform falls into this category. Please see
90 Section <ref id="sec:booting-from-C" name="Booting From C">.
92 Once you have built GHC, you can build the other Glasgow tools with
95 In theory, you can (could?) build GHC with another Haskell compiler
96 (e.g., HBC). We haven't tried to do this for ages and it almost
97 certainly doesn't work any more (for tedious reasons).
99 <tag/The CVS repository./
101 We make source distributions slightly more often than binary
102 distributions; but still infrequently. If you want more up-to-the
103 minute (but less tested) source code then you need to get access to
106 All the @fptools@ source code is held in a CVS repository. CVS is a
107 pretty good source-code control system, and best of all it works over
110 The repository holds source code only. It holds no mechanically
111 generated files at all. So if you check out a source tree from CVS
112 you will need to install every utility so that you can build all the
113 derived files from scratch.
115 More information about our CVS repository is available at <url
116 name="The Fptools CVS Cheat Sheet"
117 url="http://www.dcs.gla.ac.uk/fp/software/ghc/cvs-cheat-sheet.html">.
120 If you are going to do any building from sources (either from a source
121 distribution or the CVS repository) then you need to read all of this
124 <sect>Things to check before you start typing
127 Here's a list of things to check before you get started.
130 <idx>Disk space needed</idx>: About 30MB (five hamburgers' worth) of disk space
131 for the most basic binary distribution of GHC; more for some
132 platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
133 Haskell libraries) might take you to 8--10 hamburgers.
135 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
136 build the basic stuff from scratch.
139 All of the above are <em/estimates/ of disk-space needs.(I don't yet
140 know the disk requirements for the non-GHC tools).
143 Use an appropriate machine, compilers, and things.
145 SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
146 or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
147 in pretty good shape. Section <ref id="sec:port-info" name="Port Info">
148 gives the full run-down on ports or lack thereof.
150 NOTE: as of version 4.00, we lost a few ports. All of the x86 ports
151 are working, as is the Sparc/Solaris port, but the rest will need a
152 little work. Please contact us if you can provide hardware cycles
153 and/or porting expertise.
155 <item> Be sure that the ``pre-supposed'' utilities are installed.
156 Section <ref id="sec:pre-supposed" name="Installing Pre-Supposed
157 Utilities"> elaborates.
159 <item> If you have any problem when building or installing the Glasgow
160 tools, please check the ``known pitfalls'' (Section <ref
161 id="sec:build-pitfalls" name="Building Pitfalls">). Also check the
162 known bugs page: <url
163 url="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html">.
167 If you feel there is still some shortcoming in our procedure or
168 instructions, please report it.
170 For GHC, please see the bug-reporting section of the User's guide
171 (separate document), to maximise the usefulness of your report.
172 <nidx/bugs, reporting/
174 If in doubt, please send a message to @glasgow-haskell-bugs@@dcs.gla.ac.uk@.
175 <nidx/bugs, mailing list/
179 <sect>What machines the Glasgow tools run on
180 <label id="sec:port-info">
182 <nidx>ports, GHC</nidx>
183 <nidx>GHC ports</nidx>
184 <nidx>supported platforms</nidx>
185 <nidx>platforms, supported</nidx>
187 The main question is whether or not the Haskell compiler (GHC) runs on
190 A ``platform'' is a architecture/manufacturer/operating-system
191 combination, such as @sparc-sun-solaris2@. Other common ones are
192 @alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
193 @i386-unknown-solaris2@, @i386-unknown-freebsd@,
194 @i386-unknown-cygwin32@, @m68k-sun-sunos4@, @mips-sgi-irix5@,
195 @sparc-sun-sunos4@, @sparc-sun-solaris2@, @powerpc-ibm-aix@.
197 Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
198 work on all machines for which basic Haskell compiling is supported.
200 Some libraries may only work on a limited number of platforms; for
201 example, a sockets library is of no use unless the operating system
202 supports the underlying BSDisms.
204 <sect1>What platforms the Haskell compiler (GHC) runs on
206 <nidx>fully-supported platforms</nidx>
207 <nidx>native-code generator</nidx>
208 <nidx>registerised ports</nidx>
209 <nidx>unregisterised ports</nidx>
211 The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
212 generator; (b)~next best is a ``registerised''
213 port; (c)~the bare minimum is an ``unregisterised'' port.
214 (``Unregisterised'' is so terrible that we won't say more about it).
216 We use Sparcs running Solaris 2.5, x86 boxes running FreeBSD and
217 Linux, and DEC~Alphas running OSF/1~V2.0, so those are the
218 ``fully-supported'' platforms, unsurprisingly. All have native-code
219 generators, for quicker compilations. The native-code generator for
220 iX86 platforms (e.g., Linux ELF) is <em/nearly/ working; but is not
221 turned on by default.
223 Here's everything that's known about GHC ports. We identify platforms
224 by their ``canonical'' CPU/Manufacturer/OS triple.
226 Note that some ports are fussy about which GCC version you use; or
230 <tag/alpha-dec-osf1:/
231 <nidx>alpha-dec-osf1: fully supported</nidx>
233 (We have OSF/1 V3.0.) Fully supported, including native-code
234 generator. We recommend GCC 2.6.x or later.
236 <tag/sparc-sun-sunos4:/
237 <nidx>sparc-sun-sunos4: fully supported</nidx>
239 Fully supported, including native-code generator.
241 <tag/sparc-sun-solaris2:/
242 <nidx>sparc-sun-solaris2: fully supported</nidx>
244 Fully supported, including native-code generator. A couple of quirks,
245 though: (a)~the profiling libraries are bizarrely huge when compiled
246 with object splitting; (b)~the default @xargs@<ncdx/xargs/ program is
247 atrociously bad for building GHC libraries (see Section <ref
248 id="sec:pre-supposed" name="Installing Pre-Supposed Utilities"> for
251 <tag/HP-PA box running HP/UX 9.x:/
252 <nidx>hppa1.1-hp-hpux: registerised port</nidx>
254 Works registerised. No native-code generator. For GCC, you're best
255 off with one of the Utah releases of GCC~2.6.3 (`u3' or later), from
256 @jaguar.cs.utah.edu@. We think a straight GCC 2.7.x works,
259 Concurrent/Parallel Haskell probably don't work (yet).
260 <nidx>hppa1.1-hp-hpux: concurrent---no</nidx>
261 <nidx>hppa1.1-hp-hpux: parallel---no</nidx>
263 <tag/i386-*-linux (PCs running Linux---ELF format):/
264 <nidx>i386-*-linux: registerised port</nidx>
266 GHC works registerised. You <em/must/ have GCC 2.7.x or later. The
267 iX86 native-code generator is <em/nearly/ there, but it isn't turned
270 Profiling works, and Concurrent Haskell works.
271 <nidx>i386-*-linux: profiling---yes</nidx>
272 <nidx>i386-*-linux: concurrent---yes</nidx>
273 Parallel Haskell probably works.
274 <nidx>i386-*-linux: parallel---maybe</nidx>
276 On old Linux a.out systems: should be the same.
277 <nidx>i386-*-linuxaout: registerised port</nidx>
279 <tag>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and
280 NetBSD/OpenBSD using FreeBSD emulation):</tag>
281 <nidx>i386-*-freebsd:registerised port</nidx>
283 GHC works registerised. Supports same set of bundles as the above.
285 <nidx>i386-*-freebsd: profiling---yes</nidx>
286 <nidx>i386-*-freebsd: concurrent---yes</nidx>
287 <nidx>i386-*-freebsd: parallel---maybe</nidx>
289 <tag/i386-unknown-cygwin32:/
290 <nidx>i386-unknown-cygwin32: fully supported</nidx>
292 Fully supported under Win95/NT, including a native code
293 generator. Requires the @cygwin32@ compatibility library and a
294 healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
295 Profiling works, so does Concurrent Haskell.
297 <nidx>i386-*-cygwin32: profiling---yes</nidx>
298 <nidx>i386-*-cygwin32: concurrent---yes</nidx>
300 <tag/mips-sgi-irix5:/
301 <nidx>mips-sgi-irix5: registerised port</nidx>
303 GHC works registerised (no native-code generator). I suspect any
304 GCC~2.6.x (or later) is OK. The GCC that I used was built with
305 @--with-gnu-as@; turns out that is important!
307 Concurrent/Parallel Haskell probably don't work (yet).
308 Profiling might work, but it is untested.
309 <nidx>mips-sgi-irix5: concurrent---no</nidx>
310 <nidx>mips-sgi-irix5: parallel---no</nidx>
311 <nidx>mips-sgi-irix5: profiling---maybe</nidx>
313 <tag/mips-sgi-irix6:/
314 <nidx>mips-sgi-irix6: registerised port</nidx>
316 Thanks to the fine efforts of Tomasz Cholewo <htmlurl
317 url="mailto:tjchol01@@mecca.spd.louisville.edu"
318 name="tjchol01@@mecca.spd.louisville.edu">, GHC works registerised (no
319 native code generator) under IRIX 6.2 and 6.3. Depends on having
320 specially tweaked version of gcc-2.7.2 around, which can be downloaded
321 from <url url="http://mecca.spd.louisville.edu/~tjchol01/software/">.
323 Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
324 <nidx>mips-sgi-irix6: concurrent---maybe</nidx>
325 <nidx>mips-sgi-irix6: parallel---maybe</nidx>
326 <nidx>mips-sgi-irix6: profiling---yes</nidx>
328 <tag/powerpc-ibm-aix:/
329 <nidx>powerpc-ibm-aix: registerised port</nidx>
330 GHC works registerised (no native-code generator..yet).
331 I suspect 2.7.x is what you need together with this.
333 Concurrent/Parallel Haskell probably don't work (yet).
334 Profiling might work, but it is untested.
335 <nidx>mips-sgi-irix5: concurrent---no</nidx>
336 <nidx>mips-sgi-irix5: parallel---no</nidx>
337 <nidx>mips-sgi-irix5: profiling---maybe</nidx>
339 <tag/m68k-apple-macos7 (Mac, using MPW):/
340 <nidx>m68k-apple-macos7: historically ported</nidx>
341 Once upon a time, David Wright in Tasmania has actually
342 gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
343 You may be able to get Thomson's from here. (Not sure that it will
344 excite you to death, but...)
346 No particularly recent GHC is known to work on a Mac.
348 <tag/m68k-next-nextstep3:/
349 <nidx>m68k-next-nextstep3: historically ported</nidx>
350 Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29.
351 There's probably a little bit-rot since then, but otherwise it should
354 Concurrent/Parallel Haskell probably won't work (yet).
355 <nidx>m68k-next-nextstep3: concurrent---no</nidx>
356 <nidx>m68k-next-nextstep3: parallel---no</nidx>
358 <tag/m68k-sun-sunos4 (Sun3):/ <nidx>m68k-sun-sunos4: registerised
359 port</nidx> GHC 2.0x and 3.0x haven't been tried on a Sun3. GHC~0.26
360 worked registerised. No native-code generator.
362 Concurrent/Parallel Haskell probably don't work (yet).
363 <nidx>m68k-sun-sunos4: concurrent---no</nidx>
364 <nidx>m68k-sun-sunos4: parallel---no</nidx>
367 <sect1>What machines the other tools run on
370 Unless you hear otherwise, the other tools work if GHC works.
372 Haggis requires Concurrent Haskell to work.
373 <nidx>Haggis, Concurrent Haskell</nidx>
376 <sect>Installing from binary distributions
378 <label id="sec:installing-bin-distrib">
379 <nidx>binary installations</nidx>
380 <nidx>installation, of binaries</nidx>
382 Installing from binary distributions is easiest, and recommended!
383 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
384 so you've got to ``bootstrap'' it, somehow. We provide
385 machine-generated C-files-from-Haskell for this purpose, but it's
386 really quite a pain to use them. If you must build GHC from its
387 sources, using a binary-distributed GHC to do so is a sensible way to
388 proceed. For the other @fptools@ programs, many are written in Haskell,
389 so binary distributions allow you to install them without having a Haskell compiler.)
392 <sect1>Bundle structure<p>
393 <nidx>bundles of binary stuff</nidx>
395 Binary distributions come in ``bundles,'' one bundle per file called
396 @<bundle>-<platform>.tar.gz@. (See Section <ref
397 id="sec:port-info" name="Porting Information"> for what a platform
398 is.) Suppose that you untar a binary-distribution bundle, thus:
401 % cd /your/scratch/space
402 % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
405 Then you should find a single directory, @fptools@, with the following
408 <nidx>binary distribution, layout</nidx>
409 <nidx>directory layout (binary distributions)</nidx>
412 <tag>@Makefile.in@</tag> the raw material from which the @Makefile@
413 will be made (Section <ref id="sec:install" name="Installation">).
415 <tag>@configure@</tag> the configuration script (Section <ref
416 id="sec:install" name="Installing">).
418 <tag>@README@</tag> Contains this file summary.
420 <tag>@INSTALL@</tag> Contains this description of how to install
423 <tag>@ANNOUNCE@</tag> The announcement message for the bundle.
425 <tag>@NEWS@</tag> release notes for the bundle -- a longer version
426 of @ANNOUNCE@. For GHC, the release notes are contained in the User
427 Guide and this file isn't present.
429 <tag>@bin/<platform>@</tag> contains platform-specific executable
430 files to be invoked directly by the user. These are the files that
431 must end up in your path.
433 <tag>@lib/<platform>/@</tag> contains platform-specific support
434 files for the installation. Typically there is a subdirectory for
435 each @fptools@ project, whose name is the name of the project with its
436 version number. For example, for GHC there would be a sub-directory
437 @ghc-x.xx@/ where @x.xx@ is the version number of GHC in the bundle.
439 These sub-directories have the following general structure:
442 <tag>@libHS.a@ etc:</tag> supporting library archives.
443 <tag>@ghc-iface.prl@ etc:</tag> support scripts.
444 <tag>@import/@</tag> <idx>Interface files</idx> (@.hi@) for the prelude.
445 <tag>@include/@</tag> A few C @#include@ files.
448 <tag>@share/@</tag> contains platform-independent support files
449 for the installation. Again, there is a sub-directory for each
452 <tag>@info/@</tag> contains Emacs info documentation files (one
453 sub-directory per project).
455 <tag>@html/@</tag> contains HTML documentation files (one
456 sub-directory per project).
458 <tag>@man/@</tag> contains Unix manual pages.
462 This structure is designed so that you can unpack multiple bundles
463 (including ones from different releases or platforms) into a single
464 @fptools@ directory<footnote>this doesn't work at the
468 % cd /your/scratch/space
469 % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
470 % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -
473 When you do multiple unpacks like this, the top level @Makefile@,
474 @README@, and @INSTALL@ get overwritten each time.
475 That's fine -- they should be the same. Likewise, the
476 @ANNOUNCE-<bundle>@ and @NEWS-<bundle>@
477 files will be duplicated across multiple platforms, so they will be
478 harmlessly overwritten when you do multiple unpacks. Finally, the
479 @share/@ stuff will get harmlessly overwritten when you do
480 multiple unpacks for one bundle on different platforms.
483 <label id="sec:install">
485 OK, so let's assume that you have unpacked your chosen bundles into a
486 scratch directory @fptools@. What next? Well, you will at least need
487 to run the @configure@<ncdx/configure/ script by changing your
488 directory to @fptools@ and typing @./configure@. That should convert
489 @Makefile.in@ to @Makefile@.
491 <nidx/installing in-place/
492 <nidx/in-place installation/
494 You can now either start using the tools <em/in-situ/ without going
495 through any installation process, just type @make in-place@ to set the
496 tools up for this. You'll also want to add the path which @make@ will
497 now echo to your @PATH@ environment variable. This option is useful if
498 you simply want to try out the package and/or you don't have the
499 necessary priviledges (or inclination) to properly install the tools
500 locally. Note that if you do decide to install the package `properly'
501 at a later date, you have to go through the installation steps that
504 To install an @fptools@ package, you'll have to do the following:
507 <item> Edit the @Makefile@ and check the settings of the following variables:
509 <nidx/directories, installation/
510 <nidx/installation directories/
513 <tag>@platform@</tag> the platform you are going to install for.
515 <tag>@bindir@</tag> the directory in which to install user-invokable
518 <tag>@libdir@</tag> the directory in which to install
519 platform-dependent support files.
521 <tag>@datadir@</tag> the directory in which to install
522 platform-independent support files.
524 <tag>@infodir@</tag> the directory in which to install Emacs info
527 <tag>@htmldir@</tag> the directory in which to install HTML
530 <tag>@dvidir@</tag> the directory in which to install DVI
534 The values for these variables can be set through invocation of the
535 @configure@<ncdx/configure/ script that comes with the distribution,
536 but doing an optical diff to see if the values match your expectations
537 is always a Good Idea.
539 <em>Instead of running @configure@, it is perfectly OK to copy
540 @Makefile.in@ to @Makefile@ and set all these variables
541 directly yourself. But do it right!</em>
543 <item>Run @make install@. This <em/ should/ work with ordinary Unix
544 @make@ -- no need for fancy stuff like GNU @make@.
546 <item>@rehash@ (t?csh or zsh users), so your shell will see the new
547 stuff in your bin directory.
549 <item> Once done, test your ``installation'' as suggested in Section
550 <ref id="sec:GHC-test" name="Testing GHC">. Be sure to use a @-v@
551 option, so you can see exactly what pathnames it's using.
553 If things don't work as expected, check the list of know pitfalls in
554 Section <ref id="sec:build-pitfalls" name="Building Pitfalls">.
557 <nidx/link, installed as ghc/
558 When installing the user-invokable binaries, this installation
559 procedure will install GHC as @ghc-x.xx@ where @x.xx@ is the version
560 number of GHC. It will also make a link (in the binary installation
561 directory) from @ghc@ to @ghc-x.xx@. If you install multiple versions
562 of GHC then the last one ``wins'', and ``@ghc@'' will invoke the last
563 one installed. You can change this manually if you want. But
564 regardless, @ghc-x.xx@ should always invoke GHC version @x.xx@.
566 <sect1>What bundles there are
569 <nidx/bundles, binary/
570 There are plenty of ``non-basic'' GHC bundles. The files for them are
571 called @ghc-x.xx-<bundle>-<platform>.tar.gz@, where
572 the @<platform>@ is as above, and @<bundle>@ is one
577 <tag>@prof@:</tag> Profiling with cost-centres. You probably want this.
578 <nidx/profiling bundles/
579 <nidx/bundles, profiling/
581 <tag>@conc@:</tag> Concurrent Haskell features. You may want this.
582 <nidx/concurrent bundles/
583 <nidx/bundles, concurrent/
585 <tag>@par@:</tag> Parallel Haskell features (sits on top of PVM).
586 You'll want this if you're into that kind of thing.
587 <nidx/parallel bundles/
588 <nidx/bundles, parallel/
590 <tag>@gran@:</tag> The ``GranSim'' parallel-Haskell simulator
591 (hmm... mainly for implementors).
592 <nidx/bundles, gransim/
593 <nidx/gransim bundles/
595 <tag>@ticky@:</tag> ``Ticky-ticky'' profiling; very detailed
596 information about ``what happened when I ran this program''---really
598 <nidx/bundles, ticky-ticky/
599 <nidx/ticky-ticky bundles/
601 <tag>@prof-conc@:</tag> Cost-centre profiling for Concurrent Haskell.
602 <nidx/bundles, profiled-concurrent/
603 <nidx/profiled-concurrent bundles/
605 <tag>@prof-ticky@:</tag> Ticky-ticky profiling for Concurrent Haskell.
606 <nidx/bundles, profiled-ticky/
607 <nidx/ticky-concurrent bundles/
610 One likely scenario is that you will grab <em/three/ binary
611 bundles---basic, profiling, and concurrent. We don't usually make the
612 rest, although you can build them yourself from a source distribution.
614 <sect1>Testing that GHC seems to be working
615 <label id="sec:GHC-test">
617 <nidx>testing a new GHC</nidx>
619 The way to do this is, of course, to compile and run <em/this/ program
620 (in a file @Main.hs@):
623 main = putStr "Hello, world!\n"
626 Compile the program, using the @-v@ (verbose) flag to verify that
627 libraries, etc., are being found properly:
629 % ghc -v -o hello Main.hs
638 Some simple-but-profitable tests are to compile and run the notorious
639 @nfib@<ncdx/nfib/ program, using different numeric types. Start with
640 @nfib :: Int -> Int@, and then try @Integer@, @Float@, @Double@,
641 @Rational@ and perhaps the overloaded version. Code for this is
642 distributed in @ghc/misc/examples/nfib/@ in a source distribution.
644 For more information on how to ``drive'' GHC, either do @ghc -help@ or
645 consult the User's Guide (distributed in several pre-compiled formats
646 with a binary distribution, or in source form in
647 @ghc/docs/users_guide@ in a source distribution).
649 <sect>Installing pre-supposed utilities
650 <label id="sec:pre-supposed">
651 <nidx>pre-supposed utilities</nidx>
652 <nidx>utilities, pre-supposed</nidx>
655 Here are the gory details about some utility programs you may need;
656 @perl@ and @gcc@ are the only important ones. (<idx/PVM/ is important
657 if you're going for Parallel Haskell.) The <tt><cdx/configure/</tt>
658 script will tell you if you are missing something.
662 <nidx>pre-supposed: Perl</nidx>
663 <nidx>Perl, pre-supposed</nidx>
664 <em/You have to have Perl to proceed!/ Perl is a language quite good
665 for doing shell-scripty tasks that involve lots of text processing.
666 It is pretty easy to install.
668 Perl~5 is required. For Win32 platforms, we strongly suggest you pick
669 up a port of Perl~5 for @cygwin32@, as the common Hip/ActiveWare port
670 of Perl is not Cool Enough for our purposes.
672 Perl should be put somewhere so that it can be invoked by the @#!@
673 script-invoking mechanism. (I believe @/usr/bin/perl@ is preferred;
674 we use @/usr/local/bin/perl@ at Glasgow.) The full pathname should
675 be less than 32 characters long.
677 <tag>GNU C (@gcc@):</tag>
678 <nidx>pre-supposed: GCC (GNU C compiler)</nidx>
679 <nidx>GCC (GNU C compiler), pre-supposed</nidx>
681 Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other
682 versions at your own risk!
684 If your GCC dies with ``internal error'' on some GHC source file,
685 please let us know, so we can report it and get things improved.
686 (Exception: on @iX86@ boxes---you may need to fiddle with GHC's
687 @-monly-N-regs@ option; see the User's Guide)
689 <tag>@xargs@ on Solaris2:</tag>
690 <nidx>xargs, presupposed (Solaris only)</nidx>
691 <nidx>Solaris: alternative xargs</nidx>
692 The GHC libraries are put together with something like:
694 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
696 Unfortunately the Solaris @xargs@ (the shell-script equivalent
697 of @map@) only ``bites off'' the @.o@ files a few at a
698 time---with near-infinite rebuilding of the symbol table in
701 The best solution is to install a sane @xargs@ from the GNU
702 findutils distribution. You can unpack, build, and install the GNU
703 version in the time the Solaris @xargs@ mangles just one GHC
707 <nidx>pre-supposed: Autoconf</nidx>
708 <nidx>Autoconf, pre-supposed</nidx>
710 GNU Autoconf is needed if you intend to build from the CVS sources, it
711 is <em/not/ needed if you just intend to build a standard source
714 Autoconf builds the @configure@ script from @configure.in@ and
715 @aclocal.m4@. If you modify either of these files, you'll need
716 Autoconf to rebuild @configure@.
719 <nidx>pre-supposed: sed</nidx>
720 <nidx>sed, pre-supposed</nidx>
722 You need a working @sed@ if you are going to build from sources. The
723 build-configuration stuff needs it. GNU sed version 2.0.4 is no good!
724 It has a bug in it that is tickled by the build-configuration. 2.0.5
725 is ok. Others are probably ok too (assuming we don't create too
726 elaborate configure scripts..)
729 One @fptools@ project is worth a quick note at this point, because it
730 is useful for all the others: @glafp-utils@ contains several utilities
731 which aren't particularly Glasgow-ish, but Occasionally Indispensable.
732 Like @lndir@ for creating symbolic link trees.
734 <sect1> Tools for building parallel GHC (GPH)
735 <label id="pre-supposed-gph-tools">
739 <tag>PVM version 3:</tag>
740 <nidx>pre-supposed: PVM3 (Parallel Virtual Machine)</nidx>
741 <nidx>PVM3 (Parallel Virtual Machine), pre-supposed</nidx>
743 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
744 run. (You only need this if you plan to run Parallel Haskell.
745 Concurent Haskell, which runs concurrent threads on a uniprocessor
746 doesn't need it.) Underneath PVM, you can have (for example) a
747 network of workstations (slow) or a multiprocessor box (faster).
749 The current version of PVM is 3.3.11; we use 3.3.7. It is readily
750 available on the net; I think I got it from @research.att.com@, in
753 A PVM installation is slightly quirky, but easy to do. Just follow
754 the @Readme@ instructions.
757 <nidx>bash, presupposed (Parallel Haskell only)</nidx>
758 Sadly, the @gr2ps@ script, used to convert ``parallelism profiles''
759 to PostScript, is written in Bash (GNU's Bourne Again shell).
760 This bug will be fixed (someday).
763 <sect1> Tools for building the Documentation
764 <label id="pre-supposed-doc-tools">
767 The following additional tools are required if you want to format the
768 documentation that comes with the @fptools@ projects:
771 <tag>SGML-Tools:</tag>
772 <nidx>pre-supposed: SGML-Tools</nidx>
773 <nidx>SGML-Tools, pre-supposed</nidx>
775 All our documentation is written in SGML, using the LinuxDoc DTD that
776 comes with the SGML-Tools, which is the most shrink-wrapped SGML suite
777 that we could find. Should unpack and build painlessly on most
778 architectures, and you can use it to generate HTML, Info, LaTeX (and
779 hence DVI and Postscript), Groff, and plain text output from any
780 LinuxDoc source file (including this manual). Sources are available
781 from <url name="The SGML-Tools Web Page"
782 url="http://www.sgmltools.org/">
785 <nidx>pre-supposed: TeX</nidx>
786 <nidx>TeX, pre-supposed</nidx>
787 A decent TeX distribution is required if you want to produce printable
788 documentation. We recomment teTeX, which includes just about
792 <sect1> Other useful tools
793 <label id="pre-supposed-other-tools">
798 <nidx>pre-supposed: flex</nidx>
799 <nidx>flex, pre-supposed</nidx>
801 This is a quite-a-bit-better-than-Lex lexer. Used to build a couple
802 of utilities in @glafp-utils@. Depending on your operating system,
803 the supplied @lex@ may or may not work; you should get the GNU
807 <sect>Building from source
808 <label id="sec:building-from-source">
809 <nidx>Building from source</nidx>
810 <nidx>Source, building from</nidx>
813 You've been rash enough to want to build some of
814 the Glasgow Functional Programming tools (GHC, Happy,
815 nofib, etc) from source. You've slurped the source,
816 from the CVS repository or from a source distribution, and
817 now you're sitting looking at a huge mound of bits, wondering
820 Gingerly, you type @make@. Wrong already!
822 This rest of this guide is intended for duffers like me, who aren't
823 really interested in Makefiles and systems configurations, but who
824 need a mental model of the interlocking pieces so that they can make
825 them work, extend them consistently when adding new software, and lay
826 hands on them gently when they don't work.
828 <sect1>Your source tree
829 <label id="sec:source-tree">
832 The source code is held in your <em/source tree/.
833 The root directory of your source tree <em/must/
834 contain the following directories and files:
837 <item> @Makefile@: the root Makefile.
838 <item> @mk/@: the directory that contains the
839 main Makefile code, shared by all the
841 <item> @configure.in@, @config.sub@, @config.guess@:
842 these files support the configuration process.
846 All the other directories are individual <em/projects/ of the
847 @fptools@ system --- for example, the Glasgow Haskell Compiler
848 (@ghc@), the Happy parser generator (@happy@), the @nofib@ benchmark
849 suite, and so on. You can have zero or more of these. Needless to
850 say, some of them are needed to build others.
852 The important thing to remember is that even if you want only one
853 project (@happy@, say), you must have a source tree whose root
854 directory contains @Makefile@, @mk/@, @configure.in@, and the
855 project(s) you want (@happy/@ in this case). You cannot get by with
856 just the @happy/@ directory.
860 <nidx/link trees, for building/
863 While you can build a system in the source tree, we don't recommend it.
864 We often want to build multiple versions of our software
865 for different architectures, or with different options (e.g. profiling).
866 It's very desirable to share a single copy of the source code among
869 So for every source tree we have zero or more <em/build trees/. Each
870 build tree is initially an exact copy of the source tree, except that
871 each file is a symbolic link to the source file, rather than being a
872 copy of the source file. There are ``standard'' Unix utilities that
873 make such copies, so standard that they go by different names:
874 @lndir@<ncdx/lndir/, @mkshadowdir@<ncdx/mkshadowdir/ are two (If you
875 don't have either, the source distribution includes sources for the
876 @X11@ @lndir@ --- check out @fptools/glafp-utils/lndir@ ).
878 The build tree does not need to be anywhere near the source tree in
879 the file system. Indeed, one advantage of separating the build tree
880 from the source is that the build tree can be placed in a
881 non-backed-up partition, saving your systems support people from
882 backing up untold megabytes of easily-regenerated, and
883 rapidly-changing, gubbins. The golden rule is that (with a single
884 exception -- Section~<ref id="sec:build-config" name="Build
885 Configuration"> <em/absolutely everything in the build tree is either
886 a symbolic link to the source tree, or else is mechanically
887 generated/. It should be perfectly OK for your build tree to vanish
888 overnight; an hour or two compiling and you're on the road again.
890 You need to be a bit careful, though, that any new files you create
891 (if you do any development work) are in the source tree, not a build tree!
893 Remember, that the source files in the build tree are <em/symbolic
894 links/ to the files in the source tree. (The build tree soon
895 accumulates lots of built files like @Foo.o@, as well.) You
896 can <em/delete/ a source file from the build tree without affecting
897 the source tree (though it's an odd thing to do). On the other hand,
898 if you <em/edit/ a source file from the build tree, you'll edit the
899 source-tree file directly. (You can set up Emacs so that if you edit
900 a source file from the build tree, Emacs will silently create an
901 edited copy of the source file in the build tree, leaving the source
902 file unchanged; but the danger is that you think you've edited the
903 source file whereas actually all you've done is edit the build-tree
904 copy. More commonly you do want to edit the source file.)
906 Like the source tree, the top level of your build tree must be (a
907 linked copy of) the root directory of the @fptools@ suite. Inside
908 Makefiles, the root of your build tree is called
909 @$(FPTOOLS_TOP)@<ncdx/FPTOOLS_TOP/. In the rest of this document path
910 names are relative to @$(FPTOOLS_TOP)@ unless otherwise stated. For
911 example, the file @ghc/mk/target.mk@ is actually
912 @$(FPTOOLS_TOP)/ghc/mk/target.mk@.
915 <sect1>Getting the build you want
916 <label id="sec:build-config">
919 When you build @fptools@ you will be compiling code on a particular
920 <em/host platform/, to run on a particular <em/target platform/
921 (usually the same as the host platform)<nidx>platform</nidx>. The
922 difficulty is that there are minor differences between different
923 platforms; minor, but enough that the code needs to be a bit different
924 for each. There are some big differences too: for a different
925 architecture we need to build GHC with a different native-code
928 There are also knobs you can turn to control how the @fptools@
929 software is built. For example, you might want to build GHC optimised
930 (so that it runs fast) or unoptimised (so that you can compile it fast
931 after you've modified it. Or, you might want to compile it with
932 debugging on (so that extra consistency-checking code gets included)
935 All of this stuff is called the <em/configuration/ of your build.
936 You set the configuration using an exciting three-step process.
939 <tag>Step 1: get ready for configuration.</tag> Change directory to
940 @$(FPTOOLS_TOP)@ and issue the command @autoconf@<ncdx/autoconf/ (with
941 no arguments). This GNU program converts @$(FPTOOLS_TOP)/configure.in@
942 to a shell script called @$(FPTOOLS_TOP)/configure@.
944 Both these steps are completely platform-independent; they just mean
945 that the human-written file (@configure.in@) can be short, although
946 the resulting shell script, @configure@, and @mk/config.h.in@, are
949 In case you don't have @autoconf@ we distribute the results,
950 @configure@, and @mk/config.h.in@, with the source distribution. They
951 aren't kept in the repository, though.
953 <tag>Step 2: system configuration.</tag>
954 Runs the newly-created @configure@ script, thus:
958 @configure@'s mission is to scurry round your computer working out
959 what architecture it has, what operating system, whether it has the
960 @vfork@ system call, where @yacc@ is kept, whether @gcc@ is available,
961 where various obscure @#include@ files are, whether it's a leap year,
962 and what the systems manager had for lunch. It communicates these
963 snippets of information in two ways:
967 <item> It translates @mk/config.mk.in@<ncdx/config.mk.in/ to
968 @mk/config.mk@<ncdx/config.mk/, substituting for things between
969 ``@@@@@@@@}'' brackets. So, ``@@HaveGcc@@'' will be replaced by
970 ``@YES@'' or ``@NO@'' depending on what @configure@ finds.
971 @mk/config.mk@ is included by every Makefile (directly or indirectly),
972 so the configuration information is thereby communicated to all
975 <item> It translates @mk/config.h.in@<ncdx/config.h.in/ to
976 @mk/config.h@<ncdx/config.h/. The latter is @#include@d by various C
977 programs, which can thereby make use of configuration information.
981 @configure@ caches the results of its run in @config.cache@. Quite
982 often you don't want that; you're running @configure@ a second time
983 because something has changed. In that case, simply delete
986 <tag>Step 3: build configuration.</tag>
988 Next, you say how this build of @fptools@ is to differ from the
989 standard defaults by creating a new file @mk/build.mk@<ncdx/build.mk/
990 <em/in the build tree/. This file is the one and only file you edit
991 in the build tree, precisely because it says how this build differs
992 from the source. (Just in case your build tree does die, you might
993 want to keep a private directory of @build.mk@ files, and use a
994 symbolic link in each build tree to point to the appropriate one.) So
995 @mk/build.mk@ never exists in the source tree --- you create one in
996 each build tree from the template. We'll discuss what to put in it
1001 And that's it for configuration. Simple, eh?
1003 What do you put in your build-specific configuration file
1004 @mk/build.mk@? <em/For almost all purposes all you will do is put
1005 make variable definitions that override those in/ @mk/config.mk.in@.
1006 The whole point of @mk/config.mk.in@ --- and its derived counterpart
1007 @mk/config.mk@ --- is to define the build configuration. It is heavily
1008 commented, as you will see if you look at it. So generally, what you
1009 do is look at @mk/config.mk.in@, and add definitions in @mk/build.mk@
1010 that override any of the @config.mk@ definitions that you want to
1011 change. (The override occurs because the main boilerplate file,
1012 @mk/boilerplate.mk@<ncdx/boilerplate.mk/, includes @build.mk@ after
1015 For example, @config.mk.in@ contains the definition:
1018 ProjectsToBuild = glafp-utils ghc
1021 The accompanying comment explains that this is the list of enabled
1022 projects; that is, if (after configuring) you type @gmake all@ in
1023 @FPTOOLS_TOP@ four specified projects will be made. If you want to
1024 add @green-card@, you can add this line to @build.mk@:
1027 ProjectsToBuild += green-card
1033 ProjectsToBuild = glafp-utils ghc green-card
1036 (GNU @make@ allows existing definitions to have new text appended
1037 using the ``@+=@'' operator, which is quite a convenient feature.)
1039 When reading @config.mk.in@, remember that anything between
1040 ``@@...@@'' signs is going to be substituted by @configure@
1041 later. You <em/can/ override the resulting definition if you want,
1042 but you need to be a bit surer what you are doing. For example,
1043 there's a line that says:
1049 This defines the Make variables @YACC@ to the pathname for a Yacc that
1050 @configure@ finds somewhere. If you have your own pet Yacc you want
1051 to use instead, that's fine. Just add this line to @mk/build.mk@:
1057 You do not <em/have/ to have a @mk/build.mk@ file at all; if you
1058 don't, you'll get all the default settings from @mk/config.mk.in@.
1060 You can also use @build.mk@ to override anything that @configure@ got
1061 wrong. One place where this happens often is with the definition of
1062 @FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path
1063 to the top of your source tree, but if your system uses an automounter
1064 then the correct directory is hard to find automatically. If you find
1065 that @configure@ has got it wrong, just put the correct definition in
1068 <sect1>The story so far
1071 Let's summarise the steps you need to carry to get yourself
1072 a fully-configured build tree from scratch.
1076 <item> Get your source tree from somewhere (CVS repository or source
1077 distribution). Say you call the root directory @myfptools@ (it
1078 does not have to be called @fptools@). Make sure that you have
1079 the essential files (see Section~<ref id="sec:source-tree"
1080 name="Source Tree">).
1082 <item> Use @lndir@ or @mkshadowdir@ to create a build tree.
1085 mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1087 You probably want to give the build tree a name that
1088 suggests its main defining characteristic (in your mind at least),
1089 in case you later add others.
1091 <item> Change directory to the build tree. Everything is going
1092 to happen there now.
1094 cd /scratch/joe-bloggs/myfptools-sun4
1096 <item> Prepare for system configuration:
1100 (You can skip this step if you are starting from a source distribution,
1101 and you already have @configure@ and @mk/config.h.in@.)
1103 <item> Do system configuration:
1108 <item> Create the file @mk/build.mk@,
1109 adding definitions for your desired configuration options.
1114 You can make subsequent changes to @mk/build.mk@ as often
1115 as you like. You do not have to run any further configuration
1116 programs to make these changes take effect.
1117 In theory you should, however, say @gmake clean@, @gmake all@,
1118 because configuration option changes could affect anything --- but in practice you are likely to know what's affected.
1120 <sect1>Making things
1123 At this point you have made yourself a fully-configured build tree,
1124 so you are ready to start building real things.
1126 The first thing you need to know is that
1127 <em/you must use GNU @make@, usually called @gmake@, not standard Unix @make@/.
1128 If you use standard Unix @make@ you will get all sorts of error messages
1129 (but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities
1132 <sect1>Standard Targets
1133 <label id="sec:standard-targets">
1134 <nidx/targets, standard makefile/
1135 <nidx/makefile targets/
1138 In any directory you should be able to make the following:
1143 does the one-off preparation required to get ready for the real work.
1144 Notably, it does @gmake depend@ in all directories that contain
1145 programs. But @boot@ does more. For example, you can't do @gmake
1146 depend@ in a directory of C program until you have converted the
1147 literate @.lh@ header files into standard @.h@ header files.
1148 Similarly, you can't convert a literate file to illiterate form until
1149 you have built the @unlit@ tool. @boot@ takes care of these
1150 inter-directory dependencies.
1152 You should say @gmake boot@ right after configuring your build tree,
1153 but note that this is a one-off, i.e., there's no need to re-do
1154 @gmake boot@ if you should re-configure your build tree at a later
1155 stage (no harm caused if you do though).
1157 <tag>@all@:</tag> makes all the final target(s) for this Makefile.
1158 Depending on which directory you are in a ``final target'' may be an
1159 executable program, a library archive, a shell script, or a Postscript
1160 file. Typing @gmake@ alone is generally the same as typing @gmake
1163 <tag>@install@:</tag> installs the things built by @all@. Where does it
1164 install them? That is specified by @mk/config.mk.in@; you can
1165 override it in @mk/build.mk@.
1167 <tag>@uninstall@:</tag> reverses the effect of @install@.
1169 <tag>@clean@:</tag> remove all easily-rebuilt files.
1171 <tag>@veryclean@:</tag> remove all files that can be rebuilt at all.
1172 There's a danger here that you may remove a file that needs a more
1173 obscure utility to rebuild it (especially if you started from a source
1176 <tag>@check@:</tag> run the test suite.
1180 All of these standard targets automatically recurse into
1181 sub-directories. Certain other standard targets do not:
1185 <tag>@configure@:</tag> is only available in the root directory
1186 @$(FPTOOLS_TOP)@; it has been discussed in Section~<ref
1187 id="sec:build-config" name="Build Configuration">.
1189 <tag>@depend@:</tag> make a @.depend@ file in each directory that needs
1190 it. This @.depend@ file contains mechanically-generated dependency
1191 information; for example, suppose a directory contains a Haskell
1192 source module @Foo.lhs@ which imports another module @Baz@.
1193 Then the generated @.depend@ file will contain the dependency:
1199 which says that the object file @Foo.o@ depends on the interface file
1200 @Baz.hi@ generated by compiling module @Baz@. The @.depend@ file is
1201 automatically included by every Makefile.
1203 <tag>@binary-dist@:</tag> make a binary distribution. This is the
1204 target we use to build the binary distributions of GHC and Happy.
1206 <tag>@dist@:</tag> make a source distribution. You must be in a
1207 linked buid tree to make this target.
1210 Most @Makefiles@ have targets other than these. You can find
1211 this out by looking in the @Makefile@ itself.
1215 <nidx/dependencies, omitting/
1216 <nidx/FAST, makefile variable/
1219 Sometimes the dependencies get in the way: if you've made a small
1220 change to one file, and you're absolutely sure that it won't affect
1221 anything else, but you know that @make@ is going to rebuid everything
1222 anyway, the following hack may be useful:
1228 This tells the make system to ignore dependencies and just build what
1229 you tell it to. In other words, it's equivalent to temporarily
1230 removing the @.depend@ file in the current directory (where
1231 @mkdependHS@ and friends store their dependency information).
1233 A bit of history: GHC used to come with a @fastmake@ script that did
1234 the above job, but GNU make provides the features we need to do it
1235 without resorting to a script. Also, we've found that fastmaking is
1236 less useful since the advent of GHC's recompilation checker (see the
1237 User's Guide section on "Separate Compilation").
1239 <sect>The @Makefile@ architecture
1240 <nidx/makefile architecture/
1243 @make@ is great if everything works --- you type @gmake install@ and,
1244 lo, the right things get compiled and installed in the right places.
1245 Our goal is to make this happen often, but somehow it often doesn't;
1246 instead some wierd error message eventually emerges from the bowels of
1247 a directory you didn't know existed.
1249 The purpose of this section is to give you a road-map to help you figure
1250 out what is going right and what is going wrong.
1252 <sect1>A small project
1255 To get started, let us look at the @Makefile@ for an imaginary small
1256 @fptools@ project, @small@. Each project in @fptools@ has its own
1257 directory in @FPTOOLS_TOP@, so the @small@ project will have its own
1258 directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there
1259 will be a @Makefile@, looking something like this:
1261 <nidx/Makefile, minimal/
1263 # Makefile for fptools project "small"
1266 include $(TOP)/mk/boilerplate.mk
1268 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1271 include $(TOP)/target.mk
1274 This @Makefile@ has three sections:
1278 <item> The first section includes<footnote>One of the most important
1279 features of GNU @make@ that we use is the ability for a @Makefile@ to
1280 include another named file, very like @cpp@'s @#include@
1281 directive.</footnote> a file of ``boilerplate'' code from the level
1282 above (which in this case will be
1283 @FPTOOLS_TOP/mk/boilerplate.mk@<ncdx/boilerplate.mk/). As its name
1284 suggests, @boilerplate.mk@ consists of a large quantity of standard
1285 @Makefile@ code. We discuss this boilerplate in more detail in
1286 Section~<ref id="sec:boiler" name="Boilerplate">.
1287 <nidx/include, directive in Makefiles/
1288 <nidx/Makefile inclusion/
1290 Before the @include@ statement, you must define the @make@ variable
1291 @TOP@<ncdx/TOP/ to be the directory containing the @mk@ directory in
1292 which the @boilerplate.mk@ file is. It is <em/not/ OK to simply say
1295 include ../mk/boilerplate.mk # NO NO NO
1298 Why? Because the @boilerplate.mk@ file needs to know where it is, so
1299 that it can, in turn, @include@ other files. (Unfortunately, when an
1300 @include@d file does an @include@, the filename is treated relative to
1301 the directory in which @gmake@ is being run, not the directory in
1302 which the @included@ sits.) In general, <em>every file @foo.mk@
1303 assumes that @$(TOP)/mk/foo.mk@ refers to itself.</em> It is up to the
1304 @Makefile@ doing the @include@ to ensure this is the case.
1306 Files intended for inclusion in other @Makefile@s are written to have
1307 the following property: <em/after @foo.mk@ is @include@d, it leaves
1308 @TOP@ containing the same value as it had just before the @include@
1309 statement/. In our example, this invariant guarantees that the
1310 @include@ for @target.mk@ will look in the same directory as that for
1313 <item> The second section defines the following standard @make@
1314 variables: @SRCS@<ncdx/SRCS/ (the source files from which is to be
1315 built), and @HS_PROG@<ncdx/HS_PROG/ (the executable binary to be
1316 built). We will discuss in more detail what the ``standard
1317 variables'' are, and how they affect what happens, in Section~<ref
1318 id="sec:targets" name="Targets">.
1320 The definition for @SRCS@ uses the useful GNU @make@ construct
1321 @$(wildcard@~$pat$@)@<ncdx/wildcard/, which expands to a list of all
1322 the files matching the pattern @pat@ in the current directory. In
1323 this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@
1324 files in the directory. (Let's suppose there is one of each,
1325 @Foo.lhs@ and @Baz.c@.)
1327 <item> The last section includes a second file of standard code,
1328 called @target.mk@<ncdx/target.mk/. It contains the rules that tell
1329 @gmake@ how to make the standard targets (Section~<ref
1330 id="sec:standard-targets" name="Standard Targets">). Why, you ask,
1331 can't this standard code be part of @boilerplate.mk@? Good question.
1332 We discuss the reason later, in Section~<ref id="sec:boiler-arch"
1333 name="Boilerplate Architecture">.
1335 You do not <em/have/ to @include@ the @target.mk@ file. Instead, you
1336 can write rules of your own for all the standard targets. Usually,
1337 though, you will find quite a big payoff from using the canned rules
1338 in @target.mk@; the price tag is that you have to understand what
1339 canned rules get enabled, and what they do (Section~<ref
1340 id="sec:targets" name="Targets">.
1344 In our example @Makefile@, most of the work is done by the two
1345 @include@d files. When you say @gmake all@, the following things
1350 <item> @gmake@ figures out that the object files are @Foo.o@ and
1353 <item> It uses a boilerplate pattern rule to compile @Foo.lhs@ to
1354 @Foo.o@ using a Haskell compiler. (Which one? That is set in the
1355 build configuration.)
1357 <item> It uses another standard pattern rule to compile @Baz.c@ to
1358 @Baz.o@, using a C compiler. (Ditto.)
1360 <item> It links the resulting @.o@ files together to make @small@,
1361 using the Haskell compiler to do the link step. (Why not use @ld@?
1362 Because the Haskell compiler knows what standard librarise to link in.
1363 How did @gmake@ know to use the Haskell compiler to do the link,
1364 rather than the C compiler? Because we set the variable @HS_PROG@
1365 rather than @C_PROG@.)
1369 All @Makefile@s should follow the above three-section format.
1371 <sect1>A larger project
1374 Larger projects are usually structured into a nummber of sub-directories,
1375 each of which has its own @Makefile@. (In very large projects, this
1376 sub-structure might be iterated recursively, though that is rare.)
1377 To give you the idea, here's part of the directory structure for
1378 the (rather large) @ghc@ project:
1390 ...source files for documentation...
1394 ...source files for driver...
1398 parser/...source files for parser...
1399 renamer/...source files for renamer...
1403 The sub-directories @docs@, @driver@, @compiler@, and so on, each
1404 contains a sub-component of @ghc@, and each has its own @Makefile@.
1405 There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@. It does most
1406 of its work by recursively invoking @gmake@ on the @Makefile@s in the
1407 sub-directories. We say that @ghc/Makefile@ is a <em/non-leaf
1408 @Makefile@/, because it does little except organise its children,
1409 while the @Makefile@s in the sub-directories are all <em/leaf
1410 @Makefile@s/. (In principle the sub-directories might themselves
1411 contain a non-leaf @Makefile@ and several sub-sub-directories, but
1412 that does not happen in @ghc@.)
1414 The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even
1415 though the @ghc/compiler@ has sub-directories, because these sub-directories
1416 do not themselves have @Makefile@s in them. They are just used to structure
1417 the collection of modules that make up @ghc@, but all are managed by the
1418 single @Makefile@ in @ghc/compiler@.
1420 You will notice that @ghc/@ also contains a directory @ghc/mk/@. It
1421 contains @ghc@-specific @Makefile@ boilerplate code. More precisely:
1425 <item> @ghc/mk/boilerplate.mk@ is included at the top of
1426 @ghc/Makefile@, and of all the leaf @Makefile@s in the
1427 sub-directories. It in turn @include@s the main boilerplate file
1428 @mk/boilerplate.mk@.
1431 <item> @ghc/mk/target.mk@ is @include@d at the bottom of
1432 @ghc/Makefile@, and of all the leaf @Makefiles@ in the
1433 sub-directories. It in turn @include@s the file @mk/target.mk@.
1437 So these two files are the place to look for @ghc@-wide customisation
1438 of the standard boilerplate.
1440 <sect1>Boilerplate architecture
1441 <nidx/boilerplate architecture/
1442 <label id="sec:boiler-arch">
1445 Every @Makefile@ includes a @boilerplate.mk@<ncdx/boilerplate.mk/ file
1446 at the top, and @target.mk@<ncdx/target.mk/ file at the bottom. In
1447 this section we discuss what is in these files, and why there have to
1448 be two of them. In general:
1452 <item> @boilerplate.mk@ consists of:
1454 <item> <em/Definitions of millions of @make@ variables/ that
1455 collectively specify the build configuration. Examples:
1456 <tt><cdx/HC_OPTS/</tt>, the options to feed to the Haskell compiler;
1457 <tt><cdx/NoFibSubDirs/</tt>, the sub-directories to enable within the
1458 @nofib@ project; <tt><cdx/GhcWithHc/</tt>, the name of the Haskell
1459 compiler to use when compiling @GHC@ in the @ghc@ project. <item>
1460 <em/Standard pattern rules/ that tell @gmake@ how to construct one
1464 @boilerplate.mk@ needs to be @include@d at the <em/top/
1465 of each @Makefile@, so that the user can replace the
1466 boilerplate definitions or pattern rules by simply giving a new
1467 definition or pattern rule in the @Makefile@. @gmake@
1468 simply takes the last definition as the definitive one.
1470 Instead of <em/replacing/ boilerplate definitions, it is also quite
1471 common to <em/augment/ them. For example, a @Makefile@ might say:
1477 thereby adding ``@-O@'' to the end of <tt><cdx/SRC_HC_OPTS/</tt>.
1479 <item> @target.mk@ contains @make@ rules for the standard
1480 targets described in Section~<ref id="sec:standard-targets"
1481 name="Standard Targets">. These rules are selectively included,
1482 depending on the setting of certain @make@ variables. These
1483 variables are usually set in the middle section of the
1484 @Makefile@ between the two @include@s.
1486 @target.mk@ must be included at the end (rather than being part of
1487 @boilerplate.mk@) for several tiresome reasons:
1490 <item> @gmake@ commits target and dependency lists earlier than
1491 it should. For example, @target.mk@ has a rule that looks like
1495 $(HS_PROG) : $(OBJS)
1496 $(HC) $(LD_OPTS) $< -o $@
1499 If this rule was in @boilerplate.mk@ then @$(HS_PROG)@<ncdx/HS_PROG/
1500 and @$(OBJS)@<ncdx/OBJS/ would not have their final values at the
1501 moment @gmake@ encountered the rule. Alas, @gmake@ takes a snapshot
1502 of their current values, and wires that snapshot into the rule. (In
1503 contrast, the commands executed when the rule ``fires'' are only
1504 substituted at the moment of firing.) So, the rule must follow the
1505 definitions given in the @Makefile@ itself.
1507 <item> Unlike pattern rules, ordinary rules cannot be overriden or
1508 replaced by subsequent rules for the same target (at least not without an
1509 error message). Including ordinary rules in @boilerplate.mk@ would
1510 prevent the user from writing rules for specific targets in specific cases.
1512 <item> There are a couple of other reasons I've forgotten, but it doesn't
1517 <sect1>The main @mk/boilerplate.mk@ file
1518 <label id="sec:boiler">
1519 <ncdx/boilerplate.mk/
1522 If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find
1523 that it consists of the following sections, each held in a separate
1528 <tag><tt><cdx/config.mk/</tt></tag> is the build configuration file we
1529 discussed at length in Section~<ref id="sec:build-config" name="Build
1532 <tag><tt><cdx/paths.mk/</tt></tag> defines @make@ variables for
1533 pathnames and file lists. In particular, it gives definitions for:
1536 <tag><tt><cdx/SRCS/</tt>:</tag> all source files in the current directory.
1537 <tag><tt><cdx/HS_SRCS/</tt>:</tag> all Haskell source files in the current directory.
1538 It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value
1539 @HS_SRCS@ will follow suit.
1540 <tag><tt><cdx/C_SRCS/</tt>:</tag> similarly for C source files.
1541 <tag><tt><cdx/HS_OBJS/</tt>:</tag> the @.o@ files derived from @$(HS_SRCS)@.
1542 <tag><tt><cdx/C_OBJS/</tt>:</tag> similarly for @$(C_SRCS)@.
1543 <tag><tt><cdx/OBJS/</tt>:</tag> the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@.
1546 Any or all of these definitions can easily be overriden by giving new
1547 definitions in your @Makefile@. For example, if there are things in
1548 the current directory that look like source files but aren't, then
1549 you'll need to set @SRCS@ manually in your @Makefile@. The other
1550 definitions will then work from this new definition.
1552 What, exactly, does @paths.mk@ consider a ``source file'' to be. It's
1553 based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc), but
1554 this is the kind of detail that changes more rapidly, so rather than
1555 enumerate the source suffices here the best thing to do is to look in
1558 <tag><tt><cdx/opts.mk/</tt></tag> defines @make@ variables for option
1559 strings to pass to each program. For example, it defines
1560 <tt><cdx/HC_OPTS/</tt>, the option strings to pass to the Haskell
1561 compiler. See Section~<ref id="sec:suffix" name="Pattern Rules and
1564 <tag><tt><cdx/suffix.mk/</tt></tag> defines standard pattern rules --
1565 see Section~<ref id="sec:suffix" name="Pattern Rules and Options">.
1568 Any of the variables and pattern rules defined by the boilerplate file
1569 can easily be overridden in any particular @Makefile@, because the
1570 boilerplace @include@ comes first. Definitions after this @include@
1571 directive simply override the default ones in @boilerplate.mk@.
1573 <sect1>Pattern rules and options
1574 <label id="sec:suffix">
1575 <nidx/Pattern rules/
1578 The file @suffix.mk@<ncdx/suffix.mk/ defines standard <em/pattern
1579 rules/ that say how to build one kind of file from another, for
1580 example, how to build a @.o@ file from a @.c@ file. (GNU @make@'s
1581 <em/pattern rules/ are more powerful and easier to use than Unix
1582 @make@'s <em/suffix rules/.)
1584 Almost all the rules look something like this:
1589 $(CC) $(CC_OPTS) -c $< -o $@
1592 Here's how to understand the rule. It says that
1593 <em/something/@.o@ (say @Foo.o@) can be built from
1594 <em/something/@.c@ (@Foo.c@), by invoking the C compiler
1595 (path name held in @$(CC)@), passing to it the options
1596 @$(CC_OPTS)@ and the rule's dependent file of the rule
1597 @$<@ (@Foo.c@ in this case), and putting the result in
1598 the rule's target @$@@@ (@Foo.o@ in this case).
1600 Every program is held in a @make@ variable defined in
1601 @mk/config.mk@ --- look in @mk/config.mk@ for the
1602 complete list. One important one is the Haskell compiler, which is
1605 Every programs options are are held in a @make@ variables called
1606 @<prog>_OPTS@. the @<prog>_OPTS@ variables are defined in
1607 @mk/opts.mk@. Almost all of them are defined like this:
1610 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
1613 The four variables from which @CC_OPTS@ is built have the following meaning:
1617 <tag><tt><cdx/SRC_CC_OPTS/</tt>:</tag> options passed to all C
1620 <tag>@WAY_<way>_CC_OPTS@:</tag> options passed to C
1621 compilations for way @<way>@. For example,
1622 @WAY_mp_CC_OPTS@ gives options to pass to the C compiler when
1623 compiling way @mp@. The variable @WAY_CC_OPTS@ holds
1624 options to pass to the C compiler when compiling the standard way.
1625 (Section~<ref id="sec:ways" name="Ways"> dicusses multi-way
1626 compilation.) <tag>@<module>_CC_OPTS@:</tag> options to
1627 pass to the C compiler that are specific to module @<module>@. For example, @SMap_CC_OPTS@ gives the specific options
1628 to pass to the C compiler when compiling @SMap.c@.
1630 <tag><tt><cdx/EXTRA_CC_OPTS/</tt>:</tag> extra options to pass to all
1631 C compilations. This is intended for command line use, thus;
1634 gmake libHS.a EXTRA_CC_OPTS="-v"
1638 <sect1>The main @mk/target.mk@ file
1639 <label id="sec:targets">
1643 @target.mk@ contains canned rules for all the standard targets
1644 described in Section~<ref id="sec:standard-targets" name="Standard
1645 Targets">. It is complicated by the fact that you don't want all of
1646 these rules to be active in every @Makefile@. Rather than have a
1647 plethora of tiny files which you can include selectively, there is a
1648 single file, @target.mk@, which selectively includes rules based on
1649 whether you have defined certain variables in your @Makefile@. This
1650 section explains what rules you get, what variables control them, and
1651 what the rules do. Hopefully, you will also get enough of an idea of
1652 what is supposed to happen that you can read and understand any wierd
1653 special cases yourself.
1656 <tag><tt><cdx/HS_PROG/</tt>.</tag> If @HS_PROG@ is defined, you get
1657 rules with the following targets:
1659 <tag><tt><cdx/HS_PROG/</tt></tag> itself. This rule links @$(OBJS)@
1660 with the Haskell runtime system to get an executable called
1662 <tag><tt><cdx/install/</tt></tag> installs @$(HS_PROG)@
1663 in @$(bindir)@ with the execute bit set.
1666 <tag><tt><cdx/C_PROG/</tt></tag> is similar to @HS_PROG@, except that
1667 the link step links @$(C_OBJS)@ with the C runtime system.
1669 <tag><tt><cdx/LIBRARY/</tt></tag> is similar to @HS_PROG@, except that
1670 it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@, and
1671 @install@ installs it in @$(libdir)@, with the execute bit not set.
1673 <tag><tt><cdx/LIB_DATA/</tt></tag> ...
1674 <tag><tt><cdx/LIB_EXEC/</tt></tag> ...
1676 <tag><tt><cdx/HS_SRCS/</tt>, <tt><cdx/C_SRCS/</tt>.</tag> If @HS_SRCS@
1677 is defined and non-empty, a rule for the target @depend@ is included,
1678 which generates dependency information for Haskell programs.
1679 Similarly for @C_SRCS@.
1682 All of these rules are ``double-colon'' rules, thus
1685 install :: $(HS_PROG)
1686 ...how to install it...
1689 GNU @make@ treats double-colon rules as separate entities. If there
1690 are several double-colon rules for the same target it takes each in
1691 turn and fires it if its dependencies say to do so. This means that
1692 you can, for example, define both @HS_PROG@ and @LIBRARY@, which will
1693 generate two rules for @install@. When you type @gmake install@ both
1694 rules will be fired, and both the program and the library will be
1695 installed, just as you wanted.
1698 <label id="sec:subdirs">
1699 <nidx/recursion, in makefiles/
1700 <nidx/Makefile, recursing into subdirectories/
1703 In leaf @Makefiles@ the variable @SUBDIRS@<ncdx/SUBDIRS/ is undefined.
1704 In non-leaf @Makefiles@, @SUBDIRS@ is set to the list of
1705 sub-directories that contain subordinate @Makefile@s. <em/It is up to
1706 you to set @SUBDIRS@ in the @Makefile@./ There is no automation here
1707 --- @SUBDIRS@ is too important automate.
1709 When @SUBDIRS@ is defined, @target.mk@ includes a rather
1710 neat rule for the standard targets (Section~<ref
1711 id="sec:standard-targets" name="Standard Targets"> that simply invokes
1712 @make@ recursively in each of the sub-directories.
1714 <em/These recursive invocations are guaranteed to occur in the order
1715 in which the list of directories is specified in @SUBDIRS@./ This
1716 guarantee can be important. For example, when you say @gmake boot@ it
1717 can be important that the recursive invocation of @make boot@ is done
1718 in one sub-directory (the include files, say) before another (the
1719 source files). Generally, put the most independent sub-directory
1720 first, and the most dependent last.
1722 <sect1>Way management
1723 <label id="sec:ways">
1724 <nidx/way management/
1727 We sometimes want to build essentially the same system in several
1728 different ``ways''. For example, we want to build @ghc@'s @Prelude@
1729 libraries with and without profiling, with and without concurrency,
1730 and so on, so that there is an appropriately-built library archive to
1731 link with when the user compiles his program. It would be possible to
1732 have a completely separate build tree for each such ``way'', but it
1733 would be horribly bureaucratic, especially since often only parts of
1734 the build tree need to be constructed in multiple ways.
1736 Instead, the @target.mk@<ncdx/target.mk/ contains some clever magic to
1737 allow you to build several versions of a system; and to control
1738 locally how many versions are built and how they differ. This section
1741 The files for a particular way are distinguished by munging the
1742 suffix. The ``normal way'' is always built, and its files have the
1743 standard suffices @.o@, @.hi@, and so on. In addition, you can build
1744 one or more extra ways, each distinguished by a <em/way tag/. The
1745 object files and interface files for one of these extra ways are
1746 distinguished by their suffix. For example, way @mp@ has files
1747 @.mp_o@ and @.mp_hi@. Library archives have their way tag the other
1748 side of the dot, for boring reasons; thus, @libHS_mp.a@.
1750 A @make@ variable called @way@ holds the current way tag. <em/@way@
1751 is only ever set on the command line of a recursive invocation of
1752 @gmake@./ It is never set inside a @Makefile@. So it is a global
1753 constant for any one invocation of @gmake@. Two other @make@
1754 variables, @way_@ and @_way@ are immediately derived from @$(way)@ and
1755 never altered. If @way@ is not set, then neither are @way_@ and
1756 @_way@, and the invocation of @make@ will build the ``normal way''.
1757 If @way@ is set, then the other two variables are set in sympathy.
1758 For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@''
1759 and @_way@ is set to ``@_mp@''. These three variables are then used
1760 when constructing file names.
1762 So how does @make@ ever get recursively invoked with @way@ set? There
1763 are two ways in which this happens:
1767 <item> For some (but not all) of the standard targets, when in a leaf
1768 sub-directory, @make@ is recursively invoked for each way tag in
1769 @$(WAYS)@. You set @WAYS@ to the list of way tags you want these
1770 targets built for. The mechanism here is very much like the recursive
1771 invocation of @make@ in sub-directories (Section~<ref id="sec:subdirs"
1772 name="Subdirectories">).
1774 It is up to you to set @WAYS@ in your @Makefile@; this is how you
1775 control what ways will get built. <item> For a useful collection of
1776 targets (such as @libHS_mp.a@, @Foo.mp_o@) there is a rule which
1777 recursively invokes @make@ to make the specified target, setting the
1778 @way@ variable. So if you say @gmake Foo.mp_o@ you should see a
1779 recursive invocation @gmake Foo.mp_o way=mp@, and <em/in this
1780 recursive invocation the pattern rule for compiling a Haskell file
1781 into a @.o@ file will match/. The key pattern rules (in @suffix.mk@)
1786 $(HC) $(HC_OPTS) $< -o $@
1793 <sect1>When the canned rule isn't right
1796 Sometimes the canned rule just doesn't do the right thing. For
1797 example, in the @nofib@ suite we want the link step to print out
1798 timing information. The thing to do here is <em/not/ to define
1799 @HS_PROG@ or @C_PROG@, and instead define a special purpose rule in
1800 your own @Makefile@. By using different variable names you will avoid
1801 the canned rules being included, and conflicting with yours.
1804 <sect>Booting/porting from C (@.hc@) files
1805 <label id="sec:booting-from-C">
1806 <nidx>building GHC from .hc files</nidx>
1807 <nidx>booting GHC from .hc files</nidx>
1808 <nidx>porting GHC</nidx>
1811 This section is for people trying to get GHC going by using the
1812 supplied intermediate C (@.hc@) files. This would probably be because
1813 no binaries have been provided, or because the machine is not ``fully
1816 The intermediate C files are normally made available together with a
1817 source release, please check the announce message for exact directions
1818 of where to find them. If we've haven't made them available or you
1819 can't find them, please ask.
1821 Assuming you've got them, unpack them on top of a fresh source tree.
1822 Then follow the `normal' instructions in Section~<ref
1823 id="sec:building-from-source" name="Buiding From Source"> for setting
1824 up a build tree. When you invoke the configure script, you'll have
1825 to tell the script about your intentions:
1828 foo% ./configure --enable-hc-boot
1830 <ncdx/--enable-hc-boot/
1831 <ncdx/--disable-hc-boot/
1833 Assuming it configures OK and you don't need to create @mk/build.mk@
1834 for any other purposes, the next step is to proceed with a @make boot@
1835 followed by @make all@. At the successful completion of @make all@,
1836 you should end up with a binary of the compiler proper,
1837 @ghc/compiler/hsc@, plus archives (but no @.hi@ files!) of the prelude
1838 libraries. To generate the Prelude interface files (and test drive the
1839 bootstrapped compiler), re-run the @configure@ script, but this time
1840 witout the @--enable-hc-boot@ option. After that re-create the
1841 contents of @ghc/lib@:
1853 That's the mechanics of the boot process, but, of course, if you're
1854 trying to boot on a platform that is not supported and significantly
1855 `different' from any of the supported ones, this is only the start of
1856 the adventure...(ToDo: porting tips - stuff to look out for, etc.)
1859 <sect>Known pitfalls in building Glasgow Haskell
1860 <label id="sec:build-pitfalls">
1861 <nidx>problems, building</nidx>
1862 <nidx>pitfalls, in building</nidx>
1863 <nidx>building pitfalls</nidx>
1866 WARNINGS about pitfalls and known ``problems'':
1871 One difficulty that comes up from time to time is running out of space
1872 in @/tmp@. (It is impossible for the configuration stuff to
1873 compensate for the vagaries of different sysadmin approaches re temp
1875 <nidx/tmp, running out of space in/
1877 The quickest way around it is @setenv TMPDIR /usr/tmp@<ncdx/TMPDIR/ or
1878 even @setenv TMPDIR .@ (or the equivalent incantation with the shell
1881 The best way around it is to say
1885 in your @build.mk@ file.
1886 Then GHC and the other @fptools@ programs will use the appropriate directory
1891 In compiling some support-code bits, e.g., in @ghc/rts/gmp@ and even
1892 in @ghc/lib@, you may get a few C-compiler warnings. We think these
1896 When compiling via C, you'll sometimes get ``warning: assignment from
1897 incompatible pointer type'' out of GCC. Harmless.
1900 Similarly, @ar@chiving warning messages like the following are not
1903 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1904 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1908 <item> In compiling the compiler proper (in @compiler/@), you <em/may/
1909 get an ``Out of heap space'' error message. These can vary with the
1910 vagaries of different systems, it seems. The solution is simple:
1914 <item> If you're compiling with GHC 4.00 or above, then the
1915 <em/maximum/ heap size must have been reached. This is somewhat
1916 unlikely, since the maximum is set to 64M by default. Anyway, you can
1917 raise it with the @-optCrts-M<size>@ flag (add this flag to
1918 @<module>_HC_OPTS@ @make@ variable in the appropriate @Makefile@).
1920 <item> For GHC < 4.00, add a suitable @-H@ flag to the @Makefile@, as
1925 and try again: @gmake@. (see Section~<ref id="sec:suffix"
1926 name="Pattern Rules and Options"> for information about
1927 @<module>_HC_OPTS@.)
1929 Alternatively, just cut to the chase scene:
1932 % make EXTRA_HC_OPTS=-optCrts-M128M
1936 If you try to compile some Haskell, and you get errors from GCC about
1937 lots of things from @/usr/include/math.h@, then your GCC was
1938 mis-installed. @fixincludes@ wasn't run when it should've been.
1940 As @fixincludes@ is now automagically run as part of GCC installation,
1941 this bug also suggests that you have an old GCC.
1945 You <em/may/ need to re-@ranlib@<ncdx/ranlib/ your libraries (on Sun4s).
1948 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
1949 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
1951 ? # or, on some machines: ar s $i
1955 We'd be interested to know if this is still necessary.
1959 GHC's sources go through @cpp@ before being compiled, and @cpp@ varies
1960 a bit from one Unix to another. One particular gotcha is macro calls
1964 SLIT("Hello, world")
1967 Some @cpp@s treat the comma inside the string as separating two macro
1968 arguments, so you get
1971 :731: macro `SLIT' used with too many (2) args
1974 Alas, @cpp@ doesn't tell you the offending file!
1976 Workaround: don't put wierd things in string args to @cpp@ macros.