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>
680 Version 2.7.2.x is known to work.
682 If your GCC dies with ``internal error'' on some GHC source file,
683 please let us know, so we can report it and get things improved.
684 (Exception: on @iX86@ boxes---you may need to fiddle with GHC's
685 @-monly-N-regs@ option; see the User's Guide)
687 <nidx/EGCS/ EGCS (the Enhanced GNU Compiler Suite) may or may not
688 work, we haven't tested it fully yet.
690 <tag>PVM version 3:</tag>
691 <nidx>pre-supposed: PVM3 (Parallel Virtual Machine)</nidx>
692 <nidx>PVM3 (Parallel Virtual Machine), pre-supposed</nidx>
694 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
695 run. (You only need this if you plan to run Parallel Haskell.
696 Concurent Haskell, which runs concurrent threads on a uniprocessor
697 doesn't need it.) Underneath PVM, you can have (for example) a
698 network of workstations (slow) or a multiprocessor box (faster).
700 The current version of PVM is 3.3.11; we use 3.3.7. It is readily
701 available on the net; I think I got it from @research.att.com@, in
704 A PVM installation is slightly quirky, but easy to do. Just follow
705 the @Readme@ instructions.
707 <tag>@xargs@ on Solaris2:</tag>
708 <nidx>xargs, presupposed (Solaris only)</nidx>
709 <nidx>Solaris: alternative xargs</nidx>
710 The GHC libraries are put together with something like:
712 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
714 Unfortunately the Solaris @xargs@ (the shell-script equivalent
715 of @map@) only ``bites off'' the @.o@ files a few at a
716 time---with near-infinite rebuilding of the symbol table in
719 The best solution is to install a sane @xargs@ from the GNU
720 findutils distribution. You can unpack, build, and install the GNU
721 version in the time the Solaris @xargs@ mangles just one GHC
725 <nidx>pre-supposed: Autoconf</nidx>
726 <nidx>Autoconf, pre-supposed</nidx>
728 GNU Autoconf is used to build the @configure@ script from
729 @configure.in@ in a source distribution. If you modify
730 @configure.in@, you'll need @autoconf@ to regenerate @configure@.
732 <tag>@bash@ (Parallel Haskell only):</tag>
733 <nidx>bash, presupposed (Parallel Haskell only)</nidx>
734 Sadly, the @gr2ps@ script, used to convert ``parallelism profiles''
735 to PostScript, is written in Bash (GNU's Bourne Again shell).
736 This bug will be fixed (someday).
739 <nidx>pre-supposed: flex</nidx>
740 <nidx>flex, pre-supposed</nidx>
742 This is a quite-a-bit-better-than-Lex lexer. Used to build GHC's
743 lexer, and a couple of utilities in @glafp-utils@. On our machines,
744 the version in @/bin@ doesn't work; you need the GNU version. Find
745 out by saying @flex --version@ (our current version is 2.5.4, but
746 maybe earlier ones will work). If it doesn't know about the
747 @--version@ flag, it ain't the right @flex@.
750 <nidx>pre-supposed: non-worthless Yacc</nidx>
751 <nidx>Yacc, pre-supposed</nidx>
753 If you mess with the Haskell parser, you'll need a Yacc that can cope.
754 The unbundled @/usr/lang/yacc@ is OK; the GNU @bison@ is OK; Berkeley
755 yacc, @byacc@, is not OK.
758 <nidx>pre-supposed: sed</nidx>
759 <nidx>sed, pre-supposed</nidx>
761 You need a working @sed@ if you are going to build from sources. The
762 build-configuration stuff needs it. GNU sed version 2.0.4 is no good!
763 It has a bug in it that is tickled by the build-configuration. 2.0.5
764 is ok. Others are probably ok too (assuming we don't create too
765 elaborate configure scripts..)
769 One @fptools@ project is worth a quick note at this point, because it
770 is useful for all the others: @glafp-utils@ contains several utilities
771 which aren't particularly Glasgow-ish, but Occasionally Indispensable.
772 Like @lndir@ for creating symbolic link trees.
774 <sect1> Tools for building the Documentation
775 <label id="pre-supposed-doc-tools">
778 The following additional tools are required if you want to format the
779 documentation that comes with the @fptools@ projects:
782 <tag>SGML-Tools:</tag>
783 <nidx>pre-supposed: SGML-Tools</nidx>
784 <nidx>SGML-Tools, pre-supposed</nidx>
786 All our documentation is written in SGML, using the LinuxDoc DTD that
787 comes with the SGML-Tools, which is the most shrink-wrapped SGML suite
788 that we could find. Should unpack and build painlessly on most
789 architectures, and you can use it to generate HTML, Info, LaTeX (and
790 hence DVI and Postscript), Groff, and plain text output from any
791 LinuxDoc source file (including this manual). Sources are available
792 from <url name="The SGML-Tools Web Page"
793 url="http://www.sgmltools.org/">
796 <nidx>pre-supposed: TeX</nidx>
797 <nidx>TeX, pre-supposed</nidx>
798 A decent TeX distribution is required if you want to produce printable
799 documentation. We recomment teTeX, which includes just about
804 <sect>Building from source
805 <label id="sec:building-from-source">
806 <nidx>Building from source</nidx>
807 <nidx>Source, building from</nidx>
810 You've been rash enough to want to build some of
811 the Glasgow Functional Programming tools (GHC, Happy,
812 nofib, etc) from source. You've slurped the source,
813 from the CVS repository or from a source distribution, and
814 now you're sitting looking at a huge mound of bits, wondering
817 Gingerly, you type @make@. Wrong already!
819 This rest of this guide is intended for duffers like me, who aren't
820 really interested in Makefiles and systems configurations, but who
821 need a mental model of the interlocking pieces so that they can make
822 them work, extend them consistently when adding new software, and lay
823 hands on them gently when they don't work.
825 <sect1>Your source tree
826 <label id="sec:source-tree">
829 The source code is held in your <em/source tree/.
830 The root directory of your source tree <em/must/
831 contain the following directories and files:
834 <item> @Makefile@: the root Makefile.
835 <item> @mk/@: the directory that contains the
836 main Makefile code, shared by all the
838 <item> @configure.in@, @config.sub@, @config.guess@:
839 these files support the configuration process.
843 All the other directories are individual <em/projects/ of the
844 @fptools@ system --- for example, the Glasgow Haskell Compiler
845 (@ghc@), the Happy parser generator (@happy@), the @nofib@ benchmark
846 suite, and so on. You can have zero or more of these. Needless to
847 say, some of them are needed to build others.
849 The important thing to remember is that even if you want only one
850 project (@happy@, say), you must have a source tree whose root
851 directory contains @Makefile@, @mk/@, @configure.in@, and the
852 project(s) you want (@happy/@ in this case). You cannot get by with
853 just the @happy/@ directory.
857 <nidx/link trees, for building/
860 While you can build a system in the source tree, we don't recommend it.
861 We often want to build multiple versions of our software
862 for different architectures, or with different options (e.g. profiling).
863 It's very desirable to share a single copy of the source code among
866 So for every source tree we have zero or more <em/build trees/. Each
867 build tree is initially an exact copy of the source tree, except that
868 each file is a symbolic link to the source file, rather than being a
869 copy of the source file. There are ``standard'' Unix utilities that
870 make such copies, so standard that they go by different names:
871 @lndir@<ncdx/lndir/, @mkshadowdir@<ncdx/mkshadowdir/ are two (If you
872 don't have either, the source distribution includes sources for the
873 @X11@ @lndir@ --- check out @fptools/glafp-utils/lndir@ ).
875 The build tree does not need to be anywhere near the source tree in
876 the file system. Indeed, one advantage of separating the build tree
877 from the source is that the build tree can be placed in a
878 non-backed-up partition, saving your systems support people from
879 backing up untold megabytes of easily-regenerated, and
880 rapidly-changing, gubbins. The golden rule is that (with a single
881 exception -- Section~<ref id="sec:build-config" name="Build
882 Configuration"> <em/absolutely everything in the build tree is either
883 a symbolic link to the source tree, or else is mechanically
884 generated/. It should be perfectly OK for your build tree to vanish
885 overnight; an hour or two compiling and you're on the road again.
887 You need to be a bit careful, though, that any new files you create
888 (if you do any development work) are in the source tree, not a build tree!
890 Remember, that the source files in the build tree are <em/symbolic
891 links/ to the files in the source tree. (The build tree soon
892 accumulates lots of built files like @Foo.o@, as well.) You
893 can <em/delete/ a source file from the build tree without affecting
894 the source tree (though it's an odd thing to do). On the other hand,
895 if you <em/edit/ a source file from the build tree, you'll edit the
896 source-tree file directly. (You can set up Emacs so that if you edit
897 a source file from the build tree, Emacs will silently create an
898 edited copy of the source file in the build tree, leaving the source
899 file unchanged; but the danger is that you think you've edited the
900 source file whereas actually all you've done is edit the build-tree
901 copy. More commonly you do want to edit the source file.)
903 Like the source tree, the top level of your build tree must be (a
904 linked copy of) the root directory of the @fptools@ suite. Inside
905 Makefiles, the root of your build tree is called
906 @$(FPTOOLS_TOP)@<ncdx/FPTOOLS_TOP/. In the rest of this document path
907 names are relative to @$(FPTOOLS_TOP)@ unless otherwise stated. For
908 example, the file @ghc/mk/target.mk@ is actually
909 @$(FPTOOLS_TOP)/ghc/mk/target.mk@.
912 <sect1>Getting the build you want
913 <label id="sec:build-config">
916 When you build @fptools@ you will be compiling code on a particular
917 <em/host platform/, to run on a particular <em/target platform/
918 (usually the same as the host platform)<nidx>platform</nidx>. The
919 difficulty is that there are minor differences between different
920 platforms; minor, but enough that the code needs to be a bit different
921 for each. There are some big differences too: for a different
922 architecture we need to build GHC with a different native-code
925 There are also knobs you can turn to control how the @fptools@
926 software is built. For example, you might want to build GHC optimised
927 (so that it runs fast) or unoptimised (so that you can compile it fast
928 after you've modified it. Or, you might want to compile it with
929 debugging on (so that extra consistency-checking code gets included)
932 All of this stuff is called the <em/configuration/ of your build.
933 You set the configuration using an exciting three-step process.
936 <tag>Step 1: get ready for configuration.</tag> Change directory to
937 @$(FPTOOLS_TOP)@ and issue the command @autoconf@<ncdx/autoconf/ (with
938 no arguments). This GNU program converts @$(FPTOOLS_TOP)/configure.in@
939 to a shell script called @$(FPTOOLS_TOP)/configure@.
941 Both these steps are completely platform-independent; they just mean
942 that the human-written file (@configure.in@) can be short, although
943 the resulting shell script, @configure@, and @mk/config.h.in@, are
946 In case you don't have @autoconf@ we distribute the results,
947 @configure@, and @mk/config.h.in@, with the source distribution. They
948 aren't kept in the repository, though.
950 <tag>Step 2: system configuration.</tag>
951 Runs the newly-created @configure@ script, thus:
955 @configure@'s mission is to scurry round your computer working out
956 what architecture it has, what operating system, whether it has the
957 @vfork@ system call, where @yacc@ is kept, whether @gcc@ is available,
958 where various obscure @#include@ files are, whether it's a leap year,
959 and what the systems manager had for lunch. It communicates these
960 snippets of information in two ways:
964 <item> It translates @mk/config.mk.in@<ncdx/config.mk.in/ to
965 @mk/config.mk@<ncdx/config.mk/, substituting for things between
966 ``@@@@@@@@}'' brackets. So, ``@@HaveGcc@@'' will be replaced by
967 ``@YES@'' or ``@NO@'' depending on what @configure@ finds.
968 @mk/config.mk@ is included by every Makefile (directly or indirectly),
969 so the configuration information is thereby communicated to all
972 <item> It translates @mk/config.h.in@<ncdx/config.h.in/ to
973 @mk/config.h@<ncdx/config.h/. The latter is @#include@d by various C
974 programs, which can thereby make use of configuration information.
978 @configure@ caches the results of its run in @config.cache@. Quite
979 often you don't want that; you're running @configure@ a second time
980 because something has changed. In that case, simply delete
983 <tag>Step 3: build configuration.</tag>
985 Next, you say how this build of @fptools@ is to differ from the
986 standard defaults by creating a new file @mk/build.mk@<ncdx/build.mk/
987 <em/in the build tree/. This file is the one and only file you edit
988 in the build tree, precisely because it says how this build differs
989 from the source. (Just in case your build tree does die, you might
990 want to keep a private directory of @build.mk@ files, and use a
991 symbolic link in each build tree to point to the appropriate one.) So
992 @mk/build.mk@ never exists in the source tree --- you create one in
993 each build tree from the template. We'll discuss what to put in it
998 And that's it for configuration. Simple, eh?
1000 What do you put in your build-specific configuration file
1001 @mk/build.mk@? <em/For almost all purposes all you will do is put
1002 make variable definitions that override those in/ @mk/config.mk.in@.
1003 The whole point of @mk/config.mk.in@ --- and its derived counterpart
1004 @mk/config.mk@ --- is to define the build configuration. It is heavily
1005 commented, as you will see if you look at it. So generally, what you
1006 do is look at @mk/config.mk.in@, and add definitions in @mk/build.mk@
1007 that override any of the @config.mk@ definitions that you want to
1008 change. (The override occurs because the main boilerplate file,
1009 @mk/boilerplate.mk@<ncdx/boilerplate.mk/, includes @build.mk@ after
1012 For example, @config.mk.in@ contains the definition:
1015 ProjectsToBuild = glafp-utils ghc
1018 The accompanying comment explains that this is the list of enabled
1019 projects; that is, if (after configuring) you type @gmake all@ in
1020 @FPTOOLS_TOP@ four specified projects will be made. If you want to
1021 add @green-card@, you can add this line to @build.mk@:
1024 ProjectsToBuild += green-card
1030 ProjectsToBuild = glafp-utils ghc green-card
1033 (GNU @make@ allows existing definitions to have new text appended
1034 using the ``@+=@'' operator, which is quite a convenient feature.)
1036 When reading @config.mk.in@, remember that anything between
1037 ``@@...@@'' signs is going to be substituted by @configure@
1038 later. You <em/can/ override the resulting definition if you want,
1039 but you need to be a bit surer what you are doing. For example,
1040 there's a line that says:
1046 This defines the Make variables @YACC@ to the pathname for a Yacc that
1047 @configure@ finds somewhere. If you have your own pet Yacc you want
1048 to use instead, that's fine. Just add this line to @mk/build.mk@:
1054 You do not <em/have/ to have a @mk/build.mk@ file at all; if you
1055 don't, you'll get all the default settings from @mk/config.mk.in@.
1057 You can also use @build.mk@ to override anything that @configure@ got
1058 wrong. One place where this happens often is with the definition of
1059 @FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path
1060 to the top of your source tree, but if your system uses an automounter
1061 then the correct directory is hard to find automatically. If you find
1062 that @configure@ has got it wrong, just put the correct definition in
1065 <sect1>The story so far
1068 Let's summarise the steps you need to carry to get yourself
1069 a fully-configured build tree from scratch.
1073 <item> Get your source tree from somewhere (CVS repository or source
1074 distribution). Say you call the root directory @myfptools@ (it
1075 does not have to be called @fptools@). Make sure that you have
1076 the essential files (see Section~<ref id="sec:source-tree"
1077 name="Source Tree">).
1079 <item> Use @lndir@ or @mkshadowdir@ to create a build tree.
1082 mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
1084 You probably want to give the build tree a name that
1085 suggests its main defining characteristic (in your mind at least),
1086 in case you later add others.
1088 <item> Change directory to the build tree. Everything is going
1089 to happen there now.
1091 cd /scratch/joe-bloggs/myfptools-sun4
1093 <item> Prepare for system configuration:
1097 (You can skip this step if you are starting from a source distribution,
1098 and you already have @configure@ and @mk/config.h.in@.)
1100 <item> Do system configuration:
1105 <item> Create the file @mk/build.mk@,
1106 adding definitions for your desired configuration options.
1111 You can make subsequent changes to @mk/build.mk@ as often
1112 as you like. You do not have to run any further configuration
1113 programs to make these changes take effect.
1114 In theory you should, however, say @gmake clean@, @gmake all@,
1115 because configuration option changes could affect anything --- but in practice you are likely to know what's affected.
1117 <sect1>Making things
1120 At this point you have made yourself a fully-configured build tree,
1121 so you are ready to start building real things.
1123 The first thing you need to know is that
1124 <em/you must use GNU @make@, usually called @gmake@, not standard Unix @make@/.
1125 If you use standard Unix @make@ you will get all sorts of error messages
1126 (but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities
1129 <sect1>Standard Targets
1130 <label id="sec:standard-targets">
1131 <nidx/targets, standard makefile/
1132 <nidx/makefile targets/
1135 In any directory you should be able to make the following:
1140 does the one-off preparation required to get ready for the real work.
1141 Notably, it does @gmake depend@ in all directories that contain
1142 programs. But @boot@ does more. For example, you can't do @gmake
1143 depend@ in a directory of C program until you have converted the
1144 literate @.lh@ header files into standard @.h@ header files.
1145 Similarly, you can't convert a literate file to illiterate form until
1146 you have built the @unlit@ tool. @boot@ takes care of these
1147 inter-directory dependencies.
1149 You should say @gmake boot@ right after configuring your build tree,
1150 but note that this is a one-off, i.e., there's no need to re-do
1151 @gmake boot@ if you should re-configure your build tree at a later
1152 stage (no harm caused if you do though).
1154 <tag>@all@:</tag> makes all the final target(s) for this Makefile.
1155 Depending on which directory you are in a ``final target'' may be an
1156 executable program, a library archive, a shell script, or a Postscript
1157 file. Typing @gmake@ alone is generally the same as typing @gmake
1160 <tag>@install@:</tag> installs the things built by @all@. Where does it
1161 install them? That is specified by @mk/config.mk.in@; you can
1162 override it in @mk/build.mk@.
1164 <tag>@uninstall@:</tag> reverses the effect of @install@.
1166 <tag>@clean@:</tag> remove all easily-rebuilt files.
1168 <tag>@veryclean@:</tag> remove all files that can be rebuilt at all.
1169 There's a danger here that you may remove a file that needs a more
1170 obscure utility to rebuild it (especially if you started from a source
1173 <tag>@check@:</tag> run the test suite.
1177 All of these standard targets automatically recurse into
1178 sub-directories. Certain other standard targets do not:
1182 <tag>@configure@:</tag> is only available in the root directory
1183 @$(FPTOOLS_TOP)@; it has been discussed in Section~<ref
1184 id="sec:build-config" name="Build Configuration">.
1186 <tag>@depend@:</tag> make a @.depend@ file in each directory that needs
1187 it. This @.depend@ file contains mechanically-generated dependency
1188 information; for example, suppose a directory contains a Haskell
1189 source module @Foo.lhs@ which imports another module @Baz@.
1190 Then the generated @.depend@ file will contain the dependency:
1196 which says that the object file @Foo.o@ depends on the interface file
1197 @Baz.hi@ generated by compiling module @Baz@. The @.depend@ file is
1198 automatically included by every Makefile.
1200 <tag>@binary-dist@:</tag> make a binary distribution. This is the
1201 target we use to build the binary distributions of GHC and Happy.
1203 <tag>@dist@:</tag> make a source distribution. You must be in a
1204 linked buid tree to make this target.
1207 Most @Makefiles@ have targets other than these. You can find
1208 this out by looking in the @Makefile@ itself.
1212 <nidx/dependencies, omitting/
1213 <nidx/FAST, makefile variable/
1216 Sometimes the dependencies get in the way: if you've made a small
1217 change to one file, and you're absolutely sure that it won't affect
1218 anything else, but you know that @make@ is going to rebuid everything
1219 anyway, the following hack may be useful:
1225 This tells the make system to ignore dependencies and just build what
1226 you tell it to. In other words, it's equivalent to temporarily
1227 removing the @.depend@ file in the current directory (where
1228 @mkdependHS@ and friends store their dependency information).
1230 A bit of history: GHC used to come with a @fastmake@ script that did
1231 the above job, but GNU make provides the features we need to do it
1232 without resorting to a script. Also, we've found that fastmaking is
1233 less useful since the advent of GHC's recompilation checker (see the
1234 User's Guide section on "Separate Compilation").
1236 <sect>The @Makefile@ architecture
1237 <nidx/makefile architecture/
1240 @make@ is great if everything works --- you type @gmake install@ and,
1241 lo, the right things get compiled and installed in the right places.
1242 Our goal is to make this happen often, but somehow it often doesn't;
1243 instead some wierd error message eventually emerges from the bowels of
1244 a directory you didn't know existed.
1246 The purpose of this section is to give you a road-map to help you figure
1247 out what is going right and what is going wrong.
1249 <sect1>A small project
1252 To get started, let us look at the @Makefile@ for an imaginary small
1253 @fptools@ project, @small@. Each project in @fptools@ has its own
1254 directory in @FPTOOLS_TOP@, so the @small@ project will have its own
1255 directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there
1256 will be a @Makefile@, looking something like this:
1258 <nidx/Makefile, minimal/
1260 # Makefile for fptools project "small"
1263 include $(TOP)/mk/boilerplate.mk
1265 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1268 include $(TOP)/target.mk
1271 This @Makefile@ has three sections:
1275 <item> The first section includes<footnote>One of the most important
1276 features of GNU @make@ that we use is the ability for a @Makefile@ to
1277 include another named file, very like @cpp@'s @#include@
1278 directive.</footnote> a file of ``boilerplate'' code from the level
1279 above (which in this case will be
1280 @FPTOOLS_TOP/mk/boilerplate.mk@<ncdx/boilerplate.mk/). As its name
1281 suggests, @boilerplate.mk@ consists of a large quantity of standard
1282 @Makefile@ code. We discuss this boilerplate in more detail in
1283 Section~<ref id="sec:boiler" name="Boilerplate">.
1284 <nidx/include, directive in Makefiles/
1285 <nidx/Makefile inclusion/
1287 Before the @include@ statement, you must define the @make@ variable
1288 @TOP@<ncdx/TOP/ to be the directory containing the @mk@ directory in
1289 which the @boilerplate.mk@ file is. It is <em/not/ OK to simply say
1292 include ../mk/boilerplate.mk # NO NO NO
1295 Why? Because the @boilerplate.mk@ file needs to know where it is, so
1296 that it can, in turn, @include@ other files. (Unfortunately, when an
1297 @include@d file does an @include@, the filename is treated relative to
1298 the directory in which @gmake@ is being run, not the directory in
1299 which the @included@ sits.) In general, <em>every file @foo.mk@
1300 assumes that @$(TOP)/mk/foo.mk@ refers to itself.</em> It is up to the
1301 @Makefile@ doing the @include@ to ensure this is the case.
1303 Files intended for inclusion in other @Makefile@s are written to have
1304 the following property: <em/after @foo.mk@ is @include@d, it leaves
1305 @TOP@ containing the same value as it had just before the @include@
1306 statement/. In our example, this invariant guarantees that the
1307 @include@ for @target.mk@ will look in the same directory as that for
1310 <item> The second section defines the following standard @make@
1311 variables: @SRCS@<ncdx/SRCS/ (the source files from which is to be
1312 built), and @HS_PROG@<ncdx/HS_PROG/ (the executable binary to be
1313 built). We will discuss in more detail what the ``standard
1314 variables'' are, and how they affect what happens, in Section~<ref
1315 id="sec:targets" name="Targets">.
1317 The definition for @SRCS@ uses the useful GNU @make@ construct
1318 @$(wildcard@~$pat$@)@<ncdx/wildcard/, which expands to a list of all
1319 the files matching the pattern @pat@ in the current directory. In
1320 this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@
1321 files in the directory. (Let's suppose there is one of each,
1322 @Foo.lhs@ and @Baz.c@.)
1324 <item> The last section includes a second file of standard code,
1325 called @target.mk@<ncdx/target.mk/. It contains the rules that tell
1326 @gmake@ how to make the standard targets (Section~<ref
1327 id="sec:standard-targets" name="Standard Targets">). Why, you ask,
1328 can't this standard code be part of @boilerplate.mk@? Good question.
1329 We discuss the reason later, in Section~<ref id="sec:boiler-arch"
1330 name="Boilerplate Architecture">.
1332 You do not <em/have/ to @include@ the @target.mk@ file. Instead, you
1333 can write rules of your own for all the standard targets. Usually,
1334 though, you will find quite a big payoff from using the canned rules
1335 in @target.mk@; the price tag is that you have to understand what
1336 canned rules get enabled, and what they do (Section~<ref
1337 id="sec:targets" name="Targets">.
1341 In our example @Makefile@, most of the work is done by the two
1342 @include@d files. When you say @gmake all@, the following things
1347 <item> @gmake@ figures out that the object files are @Foo.o@ and
1350 <item> It uses a boilerplate pattern rule to compile @Foo.lhs@ to
1351 @Foo.o@ using a Haskell compiler. (Which one? That is set in the
1352 build configuration.)
1354 <item> It uses another standard pattern rule to compile @Baz.c@ to
1355 @Baz.o@, using a C compiler. (Ditto.)
1357 <item> It links the resulting @.o@ files together to make @small@,
1358 using the Haskell compiler to do the link step. (Why not use @ld@?
1359 Because the Haskell compiler knows what standard librarise to link in.
1360 How did @gmake@ know to use the Haskell compiler to do the link,
1361 rather than the C compiler? Because we set the variable @HS_PROG@
1362 rather than @C_PROG@.)
1366 All @Makefile@s should follow the above three-section format.
1368 <sect1>A larger project
1371 Larger projects are usually structured into a nummber of sub-directories,
1372 each of which has its own @Makefile@. (In very large projects, this
1373 sub-structure might be iterated recursively, though that is rare.)
1374 To give you the idea, here's part of the directory structure for
1375 the (rather large) @ghc@ project:
1387 ...source files for documentation...
1391 ...source files for driver...
1395 parser/...source files for parser...
1396 renamer/...source files for renamer...
1400 The sub-directories @docs@, @driver@, @compiler@, and so on, each
1401 contains a sub-component of @ghc@, and each has its own @Makefile@.
1402 There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@. It does most
1403 of its work by recursively invoking @gmake@ on the @Makefile@s in the
1404 sub-directories. We say that @ghc/Makefile@ is a <em/non-leaf
1405 @Makefile@/, because it does little except organise its children,
1406 while the @Makefile@s in the sub-directories are all <em/leaf
1407 @Makefile@s/. (In principle the sub-directories might themselves
1408 contain a non-leaf @Makefile@ and several sub-sub-directories, but
1409 that does not happen in @ghc@.)
1411 The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even
1412 though the @ghc/compiler@ has sub-directories, because these sub-directories
1413 do not themselves have @Makefile@s in them. They are just used to structure
1414 the collection of modules that make up @ghc@, but all are managed by the
1415 single @Makefile@ in @ghc/compiler@.
1417 You will notice that @ghc/@ also contains a directory @ghc/mk/@. It
1418 contains @ghc@-specific @Makefile@ boilerplate code. More precisely:
1422 <item> @ghc/mk/boilerplate.mk@ is included at the top of
1423 @ghc/Makefile@, and of all the leaf @Makefile@s in the
1424 sub-directories. It in turn @include@s the main boilerplate file
1425 @mk/boilerplate.mk@.
1428 <item> @ghc/mk/target.mk@ is @include@d at the bottom of
1429 @ghc/Makefile@, and of all the leaf @Makefiles@ in the
1430 sub-directories. It in turn @include@s the file @mk/target.mk@.
1434 So these two files are the place to look for @ghc@-wide customisation
1435 of the standard boilerplate.
1437 <sect1>Boilerplate architecture
1438 <nidx/boilerplate architecture/
1439 <label id="sec:boiler-arch">
1442 Every @Makefile@ includes a @boilerplate.mk@<ncdx/boilerplate.mk/ file
1443 at the top, and @target.mk@<ncdx/target.mk/ file at the bottom. In
1444 this section we discuss what is in these files, and why there have to
1445 be two of them. In general:
1449 <item> @boilerplate.mk@ consists of:
1451 <item> <em/Definitions of millions of @make@ variables/ that
1452 collectively specify the build configuration. Examples:
1453 <tt><cdx/HC_OPTS/</tt>, the options to feed to the Haskell compiler;
1454 <tt><cdx/NoFibSubDirs/</tt>, the sub-directories to enable within the
1455 @nofib@ project; <tt><cdx/GhcWithHc/</tt>, the name of the Haskell
1456 compiler to use when compiling @GHC@ in the @ghc@ project. <item>
1457 <em/Standard pattern rules/ that tell @gmake@ how to construct one
1461 @boilerplate.mk@ needs to be @include@d at the <em/top/
1462 of each @Makefile@, so that the user can replace the
1463 boilerplate definitions or pattern rules by simply giving a new
1464 definition or pattern rule in the @Makefile@. @gmake@
1465 simply takes the last definition as the definitive one.
1467 Instead of <em/replacing/ boilerplate definitions, it is also quite
1468 common to <em/augment/ them. For example, a @Makefile@ might say:
1474 thereby adding ``@-O@'' to the end of <tt><cdx/SRC_HC_OPTS/</tt>.
1476 <item> @target.mk@ contains @make@ rules for the standard
1477 targets described in Section~<ref id="sec:standard-targets"
1478 name="Standard Targets">. These rules are selectively included,
1479 depending on the setting of certain @make@ variables. These
1480 variables are usually set in the middle section of the
1481 @Makefile@ between the two @include@s.
1483 @target.mk@ must be included at the end (rather than being part of
1484 @boilerplate.mk@) for several tiresome reasons:
1487 <item> @gmake@ commits target and dependency lists earlier than
1488 it should. For example, @target.mk@ has a rule that looks like
1492 $(HS_PROG) : $(OBJS)
1493 $(HC) $(LD_OPTS) $< -o $@
1496 If this rule was in @boilerplate.mk@ then @$(HS_PROG)@<ncdx/HS_PROG/
1497 and @$(OBJS)@<ncdx/OBJS/ would not have their final values at the
1498 moment @gmake@ encountered the rule. Alas, @gmake@ takes a snapshot
1499 of their current values, and wires that snapshot into the rule. (In
1500 contrast, the commands executed when the rule ``fires'' are only
1501 substituted at the moment of firing.) So, the rule must follow the
1502 definitions given in the @Makefile@ itself.
1504 <item> Unlike pattern rules, ordinary rules cannot be overriden or
1505 replaced by subsequent rules for the same target (at least not without an
1506 error message). Including ordinary rules in @boilerplate.mk@ would
1507 prevent the user from writing rules for specific targets in specific cases.
1509 <item> There are a couple of other reasons I've forgotten, but it doesn't
1514 <sect1>The main @mk/boilerplate.mk@ file
1515 <label id="sec:boiler">
1516 <ncdx/boilerplate.mk/
1519 If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find
1520 that it consists of the following sections, each held in a separate
1525 <tag><tt><cdx/config.mk/</tt></tag> is the build configuration file we
1526 discussed at length in Section~<ref id="sec:build-config" name="Build
1529 <tag><tt><cdx/paths.mk/</tt></tag> defines @make@ variables for
1530 pathnames and file lists. In particular, it gives definitions for:
1533 <tag><tt><cdx/SRCS/</tt>:</tag> all source files in the current directory.
1534 <tag><tt><cdx/HS_SRCS/</tt>:</tag> all Haskell source files in the current directory.
1535 It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value
1536 @HS_SRCS@ will follow suit.
1537 <tag><tt><cdx/C_SRCS/</tt>:</tag> similarly for C source files.
1538 <tag><tt><cdx/HS_OBJS/</tt>:</tag> the @.o@ files derived from @$(HS_SRCS)@.
1539 <tag><tt><cdx/C_OBJS/</tt>:</tag> similarly for @$(C_SRCS)@.
1540 <tag><tt><cdx/OBJS/</tt>:</tag> the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@.
1543 Any or all of these definitions can easily be overriden by giving new
1544 definitions in your @Makefile@. For example, if there are things in
1545 the current directory that look like source files but aren't, then
1546 you'll need to set @SRCS@ manually in your @Makefile@. The other
1547 definitions will then work from this new definition.
1549 What, exactly, does @paths.mk@ consider a ``source file'' to be. It's
1550 based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc), but
1551 this is the kind of detail that changes more rapidly, so rather than
1552 enumerate the source suffices here the best thing to do is to look in
1555 <tag><tt><cdx/opts.mk/</tt></tag> defines @make@ variables for option
1556 strings to pass to each program. For example, it defines
1557 <tt><cdx/HC_OPTS/</tt>, the option strings to pass to the Haskell
1558 compiler. See Section~<ref id="sec:suffix" name="Pattern Rules and
1561 <tag><tt><cdx/suffix.mk/</tt></tag> defines standard pattern rules --
1562 see Section~<ref id="sec:suffix" name="Pattern Rules and Options">.
1565 Any of the variables and pattern rules defined by the boilerplate file
1566 can easily be overridden in any particular @Makefile@, because the
1567 boilerplace @include@ comes first. Definitions after this @include@
1568 directive simply override the default ones in @boilerplate.mk@.
1570 <sect1>Pattern rules and options
1571 <label id="sec:suffix">
1572 <nidx/Pattern rules/
1575 The file @suffix.mk@<ncdx/suffix.mk/ defines standard <em/pattern
1576 rules/ that say how to build one kind of file from another, for
1577 example, how to build a @.o@ file from a @.c@ file. (GNU @make@'s
1578 <em/pattern rules/ are more powerful and easier to use than Unix
1579 @make@'s <em/suffix rules/.)
1581 Almost all the rules look something like this:
1586 $(CC) $(CC_OPTS) -c $< -o $@
1589 Here's how to understand the rule. It says that
1590 <em/something/@.o@ (say @Foo.o@) can be built from
1591 <em/something/@.c@ (@Foo.c@), by invoking the C compiler
1592 (path name held in @$(CC)@), passing to it the options
1593 @$(CC_OPTS)@ and the rule's dependent file of the rule
1594 @$<@ (@Foo.c@ in this case), and putting the result in
1595 the rule's target @$@@@ (@Foo.o@ in this case).
1597 Every program is held in a @make@ variable defined in
1598 @mk/config.mk@ --- look in @mk/config.mk@ for the
1599 complete list. One important one is the Haskell compiler, which is
1602 Every programs options are are held in a @make@ variables called
1603 @<prog>_OPTS@. the @<prog>_OPTS@ variables are defined in
1604 @mk/opts.mk@. Almost all of them are defined like this:
1607 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
1610 The four variables from which @CC_OPTS@ is built have the following meaning:
1614 <tag><tt><cdx/SRC_CC_OPTS/</tt>:</tag> options passed to all C
1617 <tag>@WAY_<way>_CC_OPTS@:</tag> options passed to C
1618 compilations for way @<way>@. For example,
1619 @WAY_mp_CC_OPTS@ gives options to pass to the C compiler when
1620 compiling way @mp@. The variable @WAY_CC_OPTS@ holds
1621 options to pass to the C compiler when compiling the standard way.
1622 (Section~<ref id="sec:ways" name="Ways"> dicusses multi-way
1623 compilation.) <tag>@<module>_CC_OPTS@:</tag> options to
1624 pass to the C compiler that are specific to module @<module>@. For example, @SMap_CC_OPTS@ gives the specific options
1625 to pass to the C compiler when compiling @SMap.c@.
1627 <tag><tt><cdx/EXTRA_CC_OPTS/</tt>:</tag> extra options to pass to all
1628 C compilations. This is intended for command line use, thus;
1631 gmake libHS.a EXTRA_CC_OPTS="-v"
1635 <sect1>The main @mk/target.mk@ file
1636 <label id="sec:targets">
1640 @target.mk@ contains canned rules for all the standard targets
1641 described in Section~<ref id="sec:standard-targets" name="Standard
1642 Targets">. It is complicated by the fact that you don't want all of
1643 these rules to be active in every @Makefile@. Rather than have a
1644 plethora of tiny files which you can include selectively, there is a
1645 single file, @target.mk@, which selectively includes rules based on
1646 whether you have defined certain variables in your @Makefile@. This
1647 section explains what rules you get, what variables control them, and
1648 what the rules do. Hopefully, you will also get enough of an idea of
1649 what is supposed to happen that you can read and understand any wierd
1650 special cases yourself.
1653 <tag><tt><cdx/HS_PROG/</tt>.</tag> If @HS_PROG@ is defined, you get
1654 rules with the following targets:
1656 <tag><tt><cdx/HS_PROG/</tt></tag> itself. This rule links @$(OBJS)@
1657 with the Haskell runtime system to get an executable called
1659 <tag><tt><cdx/install/</tt></tag> installs @$(HS_PROG)@
1660 in @$(bindir)@ with the execute bit set.
1663 <tag><tt><cdx/C_PROG/</tt></tag> is similar to @HS_PROG@, except that
1664 the link step links @$(C_OBJS)@ with the C runtime system.
1666 <tag><tt><cdx/LIBRARY/</tt></tag> is similar to @HS_PROG@, except that
1667 it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@, and
1668 @install@ installs it in @$(libdir)@, with the execute bit not set.
1670 <tag><tt><cdx/LIB_DATA/</tt></tag> ...
1671 <tag><tt><cdx/LIB_EXEC/</tt></tag> ...
1673 <tag><tt><cdx/HS_SRCS/</tt>, <tt><cdx/C_SRCS/</tt>.</tag> If @HS_SRCS@
1674 is defined and non-empty, a rule for the target @depend@ is included,
1675 which generates dependency information for Haskell programs.
1676 Similarly for @C_SRCS@.
1679 All of these rules are ``double-colon'' rules, thus
1682 install :: $(HS_PROG)
1683 ...how to install it...
1686 GNU @make@ treats double-colon rules as separate entities. If there
1687 are several double-colon rules for the same target it takes each in
1688 turn and fires it if its dependencies say to do so. This means that
1689 you can, for example, define both @HS_PROG@ and @LIBRARY@, which will
1690 generate two rules for @install@. When you type @gmake install@ both
1691 rules will be fired, and both the program and the library will be
1692 installed, just as you wanted.
1695 <label id="sec:subdirs">
1696 <nidx/recursion, in makefiles/
1697 <nidx/Makefile, recursing into subdirectories/
1700 In leaf @Makefiles@ the variable @SUBDIRS@<ncdx/SUBDIRS/ is undefined.
1701 In non-leaf @Makefiles@, @SUBDIRS@ is set to the list of
1702 sub-directories that contain subordinate @Makefile@s. <em/It is up to
1703 you to set @SUBDIRS@ in the @Makefile@./ There is no automation here
1704 --- @SUBDIRS@ is too important automate.
1706 When @SUBDIRS@ is defined, @target.mk@ includes a rather
1707 neat rule for the standard targets (Section~<ref
1708 id="sec:standard-targets" name="Standard Targets"> that simply invokes
1709 @make@ recursively in each of the sub-directories.
1711 <em/These recursive invocations are guaranteed to occur in the order
1712 in which the list of directories is specified in @SUBDIRS@./ This
1713 guarantee can be important. For example, when you say @gmake boot@ it
1714 can be important that the recursive invocation of @make boot@ is done
1715 in one sub-directory (the include files, say) before another (the
1716 source files). Generally, put the most independent sub-directory
1717 first, and the most dependent last.
1719 <sect1>Way management
1720 <label id="sec:ways">
1721 <nidx/way management/
1724 We sometimes want to build essentially the same system in several
1725 different ``ways''. For example, we want to build @ghc@'s @Prelude@
1726 libraries with and without profiling, with and without concurrency,
1727 and so on, so that there is an appropriately-built library archive to
1728 link with when the user compiles his program. It would be possible to
1729 have a completely separate build tree for each such ``way'', but it
1730 would be horribly bureaucratic, especially since often only parts of
1731 the build tree need to be constructed in multiple ways.
1733 Instead, the @target.mk@<ncdx/target.mk/ contains some clever magic to
1734 allow you to build several versions of a system; and to control
1735 locally how many versions are built and how they differ. This section
1738 The files for a particular way are distinguished by munging the
1739 suffix. The ``normal way'' is always built, and its files have the
1740 standard suffices @.o@, @.hi@, and so on. In addition, you can build
1741 one or more extra ways, each distinguished by a <em/way tag/. The
1742 object files and interface files for one of these extra ways are
1743 distinguished by their suffix. For example, way @mp@ has files
1744 @.mp_o@ and @.mp_hi@. Library archives have their way tag the other
1745 side of the dot, for boring reasons; thus, @libHS_mp.a@.
1747 A @make@ variable called @way@ holds the current way tag. <em/@way@
1748 is only ever set on the command line of a recursive invocation of
1749 @gmake@./ It is never set inside a @Makefile@. So it is a global
1750 constant for any one invocation of @gmake@. Two other @make@
1751 variables, @way_@ and @_way@ are immediately derived from @$(way)@ and
1752 never altered. If @way@ is not set, then neither are @way_@ and
1753 @_way@, and the invocation of @make@ will build the ``normal way''.
1754 If @way@ is set, then the other two variables are set in sympathy.
1755 For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@''
1756 and @_way@ is set to ``@_mp@''. These three variables are then used
1757 when constructing file names.
1759 So how does @make@ ever get recursively invoked with @way@ set? There
1760 are two ways in which this happens:
1764 <item> For some (but not all) of the standard targets, when in a leaf
1765 sub-directory, @make@ is recursively invoked for each way tag in
1766 @$(WAYS)@. You set @WAYS@ to the list of way tags you want these
1767 targets built for. The mechanism here is very much like the recursive
1768 invocation of @make@ in sub-directories (Section~<ref id="sec:subdirs"
1769 name="Subdirectories">).
1771 It is up to you to set @WAYS@ in your @Makefile@; this is how you
1772 control what ways will get built. <item> For a useful collection of
1773 targets (such as @libHS_mp.a@, @Foo.mp_o@) there is a rule which
1774 recursively invokes @make@ to make the specified target, setting the
1775 @way@ variable. So if you say @gmake Foo.mp_o@ you should see a
1776 recursive invocation @gmake Foo.mp_o way=mp@, and <em/in this
1777 recursive invocation the pattern rule for compiling a Haskell file
1778 into a @.o@ file will match/. The key pattern rules (in @suffix.mk@)
1783 $(HC) $(HC_OPTS) $< -o $@
1790 <sect1>When the canned rule isn't right
1793 Sometimes the canned rule just doesn't do the right thing. For
1794 example, in the @nofib@ suite we want the link step to print out
1795 timing information. The thing to do here is <em/not/ to define
1796 @HS_PROG@ or @C_PROG@, and instead define a special purpose rule in
1797 your own @Makefile@. By using different variable names you will avoid
1798 the canned rules being included, and conflicting with yours.
1801 <sect>Booting/porting from C (@.hc@) files
1802 <label id="sec:booting-from-C">
1803 <nidx>building GHC from .hc files</nidx>
1804 <nidx>booting GHC from .hc files</nidx>
1805 <nidx>porting GHC</nidx>
1808 This section is for people trying to get GHC going by using the
1809 supplied intermediate C (@.hc@) files. This would probably be because
1810 no binaries have been provided, or because the machine is not ``fully
1813 The intermediate C files are normally made available together with a
1814 source release, please check the announce message for exact directions
1815 of where to find them. If we've haven't made them available or you
1816 can't find them, please ask.
1818 Assuming you've got them, unpack them on top of a fresh source tree.
1819 Then follow the `normal' instructions in Section~<ref
1820 id="sec:building-from-source" name="Buiding From Source"> for setting
1821 up a build tree. When you invoke the configure script, you'll have
1822 to tell the script about your intentions:
1825 foo% ./configure --enable-hc-boot
1827 <ncdx/--enable-hc-boot/
1828 <ncdx/--disable-hc-boot/
1830 Assuming it configures OK and you don't need to create @mk/build.mk@
1831 for any other purposes, the next step is to proceed with a @make boot@
1832 followed by @make all@. At the successful completion of @make all@,
1833 you should end up with a binary of the compiler proper,
1834 @ghc/compiler/hsc@, plus archives (but no @.hi@ files!) of the prelude
1835 libraries. To generate the Prelude interface files (and test drive the
1836 bootstrapped compiler), re-run the @configure@ script, but this time
1837 witout the @--enable-hc-boot@ option. After that re-create the
1838 contents of @ghc/lib@:
1850 That's the mechanics of the boot process, but, of course, if you're
1851 trying to boot on a platform that is not supported and significantly
1852 `different' from any of the supported ones, this is only the start of
1853 the adventure...(ToDo: porting tips - stuff to look out for, etc.)
1856 <sect>Known pitfalls in building Glasgow Haskell
1857 <label id="sec:build-pitfalls">
1858 <nidx>problems, building</nidx>
1859 <nidx>pitfalls, in building</nidx>
1860 <nidx>building pitfalls</nidx>
1863 WARNINGS about pitfalls and known ``problems'':
1868 One difficulty that comes up from time to time is running out of space
1869 in @/tmp@. (It is impossible for the configuration stuff to
1870 compensate for the vagaries of different sysadmin approaches re temp
1872 <nidx/tmp, running out of space in/
1874 The quickest way around it is @setenv TMPDIR /usr/tmp@<ncdx/TMPDIR/ or
1875 even @setenv TMPDIR .@ (or the equivalent incantation with the shell
1878 The best way around it is to say
1882 in your @build.mk@ file.
1883 Then GHC and the other @fptools@ programs will use the appropriate directory
1888 In compiling some support-code bits, e.g., in @ghc/rts/gmp@ and even
1889 in @ghc/lib@, you may get a few C-compiler warnings. We think these
1893 When compiling via C, you'll sometimes get ``warning: assignment from
1894 incompatible pointer type'' out of GCC. Harmless.
1897 Similarly, @ar@chiving warning messages like the following are not
1900 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1901 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1905 <item> In compiling the compiler proper (in @compiler/@), you <em/may/
1906 get an ``Out of heap space'' error message. These can vary with the
1907 vagaries of different systems, it seems. The solution is simple:
1911 <item> If you're compiling with GHC 4.00 or above, then the
1912 <em/maximum/ heap size must have been reached. This is somewhat
1913 unlikely, since the maximum is set to 64M by default. Anyway, you can
1914 raise it with the @-optCrts-M<size>@ flag (add this flag to
1915 @<module>_HC_OPTS@ @make@ variable in the appropriate @Makefile@).
1917 <item> For GHC < 4.00, add a suitable @-H@ flag to the @Makefile@, as
1922 and try again: @gmake@. (see Section~<ref id="sec:suffix"
1923 name="Pattern Rules and Options"> for information about
1924 @<module>_HC_OPTS@.)
1926 Alternatively, just cut to the chase scene:
1929 % make EXTRA_HC_OPTS=-optCrts-M128M
1933 If you try to compile some Haskell, and you get errors from GCC about
1934 lots of things from @/usr/include/math.h@, then your GCC was
1935 mis-installed. @fixincludes@ wasn't run when it should've been.
1937 As @fixincludes@ is now automagically run as part of GCC installation,
1938 this bug also suggests that you have an old GCC.
1942 You <em/may/ need to re-@ranlib@<ncdx/ranlib/ your libraries (on Sun4s).
1945 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
1946 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
1948 ? # or, on some machines: ar s $i
1952 We'd be interested to know if this is still necessary.
1956 GHC's sources go through @cpp@ before being compiled, and @cpp@ varies
1957 a bit from one Unix to another. One particular gotcha is macro calls
1961 SLIT("Hello, world")
1964 Some @cpp@s treat the comma inside the string as separating two macro
1965 arguments, so you get
1968 :731: macro `SLIT' used with too many (2) args
1971 Alas, @cpp@ doesn't tell you the offending file!
1973 Workaround: don't put wierd things in string args to @cpp@ macros.