1 % Building and installing the Glasgow Functional Programming Tools Suite
8 \documentstyle[11pt,literate]{article}
10 \title{Building and installing the Glasgow Functional Programming Tools Suite\\
12 \author{The GHC Team\\
13 Department of Computing Science\\
14 University of Glasgow\\
18 Email: glasgow-haskell-\{users,bugs\}\@dcs.gla.ac.uk}
26 This guide is intended for people who want to install or modify
27 programs from the Glasgow @fptools@ suite (as distinct from those
28 who merely want to {\em run} them).
30 The whole install-and-make system was completely re-done between GHC
31 2.01 and 2.02, so it will be worth your while to re-read this guide
32 even if you have read earlier versions.
34 \section{Getting the Glasgow @fptools@ suite}
36 Building the Glasgow tools {\em can} be complicated, mostly because
37 there are so many permutations of what/why/how, e.g., ``Build Happy
38 with HBC, everything else with GHC, leave out profiling, and test it
39 all on the `real' NoFib programs.'' Yeeps!
41 Happily, such complications don't apply to most people. A few common
42 ``strategies'' serve most purposes. Pick one and proceed
46 \item[Binary distribution.] If your only purpose is to install
47 some of the @fptools@ suite then the easiest thing to do is to
48 get a binary distribution. In the binary distribution everything is
49 pre-compiled for your particular machine architecture and operating
50 system, so all you should have to do is install the binaries and libraries
51 in suitable places. {\em Need pointer to info about doing binary installation.}
53 A binary distribution may not work for you for two reasons. First, we
54 may not have built the suite for the particular architecture/OS
55 platform you want. That may be due to lack of time and energy (in
56 which case you can get a source distribution and build from it; see
57 below). Alternatively, it may be because we haven't yet ported the
58 suite to your architecture, in which case you are considerably worse
61 The second reason a binary distribution may not be what you want is
62 if you want to read or modify the souce code.
64 \item[Source distribution.]
65 You have a supported platform, but (a)~you like the warm fuzzy feeling
66 of compiling things yourself; (b)~you want to build something
67 ``extra''---e.g., a set of libraries with strictness-analysis turned
68 off; or (c)~you want to hack on GHC yourself.
70 A source distribution contains complete sources for the @fptools@ suite.
71 Not only that, but the more awkward machine-independent steps are done
72 for you. For example, if you don't have @flex@ you'll find it
73 convenient that the source distribution contains the result of running
74 @flex@ on the lexical analyser specification. If you don't want to
75 alter the lexical analyser then this saves you having to find and
76 install @flex@. You will still need a working version of GHC on your
77 machine in order to compile (most of) the sources, however.
79 We make source distributions more frequently than binary
80 distributions; a release that comes with pre-compiled binaries
81 is considered a major release, i.e., a release that we have some
82 confidence will work well by having tested it (more) thoroughly.
84 Source-only distributions are either bugfix releases or snapshots of
85 current state of development. The release has undergone some testing.
87 GHC~2.04 is a source-only release, and it can be compiled up using
88 either GHC~2.02 (or the bugfix release, GHC~2.03) or the Good Old
89 Compiler, GHC~0.29. Compiling with 0.29 is recommended if you're
90 a performance junkie, as 0.29 (still) generates zippier code, but
91 GHC~2.04 is catching up.
93 \item[Build GHC from intermediate C \tr{.hc} files:]
94 You need a working GHC to use a source distribution. What if you don't
95 have a working GHC? Then you have no choice but to ``bootstrap'' up
96 from the intermediate C (\tr{.hc}) files that we provide.
97 Building GHC on an unsupported platform falls into this category.
98 Please see \sectionref{booting-from-C}.
100 Once you have built GHC, you can build the other Glasgow tools with
103 In theory, you can (could?) build GHC with another Haskell compiler
104 (e.g., HBC). We haven't tried to do this for ages and it almost
105 certainly doesn't work any more (for tedious reasons).
107 \item[The CVS repository.]
109 We make source distributions at the same time as binary distributions;
110 i.e. infrequently. They should, however, be pretty thoroughly tested.
111 If you want more up-to-the minute (but less tested) source code then you
112 need to get access to our CVS repository.
114 All the @fptools@ source code is held in a CVS repository. CVS is a
115 pretty good source-code control system, and best of all it works over
118 The repository holds source code only. It holds no mechanically
119 generated files at all. So if you check out a source tree from CVS
120 you will need to install every utility so that you can build all the
121 derived files from scratch.
123 Giving you access to the repository entails some systems administration
124 at our end; and we are a bit nervous about being submerged in bug reports
125 about our current working copy (which is, by definition, in flux). So
126 we are a bit cautious about offering CVS access. Feel free to ask though!
129 If you are going to do any building from sources (either from a source
130 distribution or the CVS repository) then you need to read all of this
133 %************************************************************************
135 \section{Things to check before you start typing}
137 %************************************************************************
139 Here's a list of things to check before you get started.
142 \index{disk space needed}
143 Disk space needed: About 30MB (five hamburgers' worth) of disk space
144 for the most basic binary distribution of GHC; more for some
145 platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
146 Haskell libraries) might take you to 8--10 hamburgers.
148 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
149 build the basic stuff from scratch.
152 All of the above are {\em estimates} of disk-space needs.(I don't yet
153 know the disk requirements for the non-GHC tools).
156 Use an appropriate machine, compilers, and things.
158 SPARC boxes and DEC Alphas running OSF/1 are fully supported.
159 Linux, MIPS, AIX, Win32 and HP boxes are in pretty good shape.
160 \Sectionref{port-info} gives the full run-down on ports or lack
164 Be sure that the ``pre-supposed'' utilities are installed.
165 Section~\ref{sect_std-utils} elaborates.
168 If you have any problem when building or installing the Glasgow tools,
169 please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If
170 you feel there is still some shortcoming in our procedure or
171 instructions, please report it.
173 For GHC, please see the bug-reporting section of the User's guide
174 (separate document), to maximise the usefulness of your report.
176 If in doubt, please send a message to \tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
180 %************************************************************************
182 \section[port-info]{What machines the Glasgow tools, version~2.04, run on}
185 \index{supported platforms}
186 \index{platforms, supported}
188 %************************************************************************
190 The main question is whether or not the Haskell compiler (GHC) runs on
194 architecture/manufacturer/operating-system combination,
195 such as @sparc-sun-solaris2.5.1@. Other common ones are
196 @alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
197 @i386-unknown-solaris2@, @i386-unknown-freebsd@, @i386-unknown-cygwin32@,
198 @m68k-sun-sunos4@, @mips-sgi-irix5@, @sparc-sun-sunos4@,
199 @sparc-sun-solaris2@, @powerpc-ibm-aix@.
201 Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
202 work on all machines for which basic Haskell compiling is supported.
204 Some libraries may only work on a limited number of platforms; for
205 example, a sockets library is of no use unless the operating system
206 supports the underlying BSDisms.
208 %************************************************************************
210 \subsection{What platforms the Haskell compiler (GHC) runs on}
212 %************************************************************************
213 \index{fully-supported platforms}
214 \index{native-code generator}
215 \index{registerised ports}
216 \index{unregisterised ports}
218 The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
219 generator; (b)~next best is a ``registerised''
220 port; (c)~the bare minimum is an ``unregisterised'' port.
221 (``Unregisterised'' is so terrible that we won't say more about it).
223 We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas
224 running OSF/1~V2.0, so those are the ``fully-supported'' platforms,
225 unsurprisingly. Both have native-code generators, for quicker
226 compilations. The native-code generator for iX86 platforms (e.g.,
227 Linux ELF) is {\em nearly} working; but is not turned on by default.
229 Here's everything that's known about GHC ports, as of 2.04. We
230 identify platforms by their ``canonical'' CPU/Manufacturer/OS triple.
232 Note that some ports are fussy about which GCC version you use; or
236 %-------------------------------------------------------------------
237 \item[\tr{alpha-dec-osf1}:]
238 \index{alpha-dec-osf1: fully supported}
239 (We have OSF/1 V2.0.) Fully supported, including native-code generator.
240 We recommend GCC 2.6.x or later.
242 %-------------------------------------------------------------------
243 \item[\tr{sparc-sun-sunos4}:]
244 \index{sparc-sun-sunos4: fully supported}
245 Fully supported, including native-code generator.
247 %-------------------------------------------------------------------
248 \item[\tr{sparc-sun-solaris2}:]
249 \index{sparc-sun-solaris2: fully supported}
250 Fully supported, including native-code generator. A couple of quirks,
251 though: (a)~the profiling libraries are bizarrely huge; (b)~the
252 default \tr{xargs} program is atrociously bad for building GHC
253 libraries (see \sectionref{Pre-supposed} for details).
255 %-------------------------------------------------------------------
256 \item[HP-PA box running HP/UX 9.x:]
257 \index{hppa1.1-hp-hpux: registerised port}
258 Works registerised. No native-code generator.
259 For GCC, you're best off with one of the Utah releases of
260 GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}.
261 We think a straight GCC 2.7.x works, too.
263 Concurrent/Parallel Haskell probably don't work (yet).
264 \index{hppa1.1-hp-hpux: concurrent---no}
265 \index{hppa1.1-hp-hpux: parallel---no}
267 %-------------------------------------------------------------------
268 \item[\tr{i386-*-linux} (PCs running Linux---ELF format):]
269 \index{i386-*-linux: registerised port}
270 GHC~2.04 works registerised.
271 You {\em must} have GCC 2.7.x or later.
272 The iX86 native-code generator is {\em nearly} there, but it
273 isn't turned on by default.
275 Profiling works, and Concurrent Haskell works.
276 \index{i386-*-linux: profiling---yes}
277 \index{i386-*-linux: concurrent---yes}
278 Parallel Haskell probably works.
279 \index{i386-*-linux: parallel---maybe}
281 On old Linux a.out systems: should be the same.
282 \index{i386-*-linuxaout: registerised port}
284 %-------------------------------------------------------------------
285 \item[\tr{i386-*-freebsd} (PCs running FreeBSD 2.2 or higher, and
286 NetBSD/OpenBSD using FreeBSD emulation):] \index{i386-*-freebsd:
287 registerised port} GHC~2.04 works registerised. Supports same set of
288 bundles as the above.
290 \index{i386-*-freebsd: profiling---yes}
291 \index{i386-*-freebsd: concurrent---yes}
292 \index{i386-*-freebsd: parallel---maybe}
294 %-------------------------------------------------------------------
295 \item[\tr{i386-unknown-cygwin32}:]
296 \index{i386-unknown-cygwin32: fully supported}
297 Fully supported under Win95/NT, including a native
298 code generator. Requires the @cygwin32@ compatibility library and
299 a healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
300 Profiling works, so does Concurrent Haskell.
301 \index{i386-*-cygwin32: profiling---yes}
302 \index{i386-*-cygwin32: concurrent---yes}
304 % ToDo: more documentation on this is reqd here.
306 %-------------------------------------------------------------------
307 \item[\tr{mips-sgi-irix5}:]
308 \index{mips-sgi-irix5: registerised port}
309 GHC~2.04 works registerised (no native-code generator).
310 I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
311 was built with \tr{--with-gnu-as}; turns out that is important!
313 Concurrent/Parallel Haskell probably don't work (yet).
314 Profiling might work, but it is untested.
315 \index{mips-sgi-irix5: concurrent---no}
316 \index{mips-sgi-irix5: parallel---no}
317 \index{mips-sgi-irix5: profiling---maybe}
319 %-------------------------------------------------------------------
320 \item[\tr{mips-sgi-irix6}:]
321 \index{mips-sgi-irix6: registerised port}
322 Thanks to the fine efforts of Tomasz Cholewo
323 \tr{<tjchol01@mecca.spd.louisville.edu>}, GHC~2.04 works registerised
324 (no native code generator) under IRIX 6.2 and 6.3. Depends on having
325 specially tweaked version of gcc-2.7.2 around, which can be downloaded
329 http://mecca.spd.louisville.edu/~tjchol01/software/
332 Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
333 \index{mips-sgi-irix6: concurrent---maybe}
334 \index{mips-sgi-irix6: parallel---maybe}
335 \index{mips-sgi-irix6: profiling---yes}
337 %-------------------------------------------------------------------
338 \item[\tr{powerpc-ibm-aix}:]
339 \index{powerpc-ibm-aix: registerised port}
340 GHC~2.04 works registerised (no native-code generator..yet).
341 I suspect 2.7.x is what you need together with this.
343 Concurrent/Parallel Haskell probably don't work (yet).
344 Profiling might work, but it is untested.
345 \index{mips-sgi-irix5: concurrent---no}
346 \index{mips-sgi-irix5: parallel---no}
347 \index{mips-sgi-irix5: profiling---maybe}
349 %-------------------------------------------------------------------
350 \item[\tr{m68k-apple-macos7} (Mac, using MPW):]
351 \index{m68k-apple-macos7: historically ported}
352 Once upon a time, David Wright in Tasmania has actually
353 gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
354 You may be able to get Thomson's from here. (Not sure that it will
355 excite you to death, but...)
357 No particularly recent GHC is known to work on a Mac.
359 %-------------------------------------------------------------------
360 \item[\tr{m68k-next-nextstep3}:]
361 \index{m68k-next-nextstep3: historically ported}
362 Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29.
363 There's probably a little bit-rot since then, but otherwise it should
366 Concurrent/Parallel Haskell probably won't work (yet).
367 \index{m68k-next-nextstep3: concurrent---no}
368 \index{m68k-next-nextstep3: parallel---no}
370 %-------------------------------------------------------------------
371 \item[\tr{m68k-sun-sunos4} (Sun3):]
372 \index{m68k-sun-sunos4: registerised port}
373 GHC~2.04 hasn't been tried on a Sun3. GHC~0.26 worked registerised.
374 No native-code generator.
376 Concurrent/Parallel Haskell probably don't work (yet).
377 \index{m68k-sun-sunos4: concurrent---no}
378 \index{m68k-sun-sunos4: parallel---no}
381 %************************************************************************
383 \subsection{What machines the other tools run on}
385 %************************************************************************
387 Unless you hear otherwise, the other tools work if GHC works.
389 Haggis requires Concurrent Haskell to work.
390 \index{Haggis, Concurrent Haskell}
393 %************************************************************************
395 \section[installing-bin-distrib]{Installing from binary distributions}
396 \index{binary installations}
397 \index{installation, of binaries}
399 %************************************************************************
401 Installing from binary distributions is easiest, and recommended!
402 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
403 so you've got to ``bootstrap'' it, somehow. We provide
404 machine-generated C-files-from-Haskell for this purpose, but it's
405 really quite a pain to use them. If you must build GHC from its
406 sources, using a binary-distributed GHC to do so is a sensible way to
407 proceed. For the other @fptools@ programs, many are written in Haskell,
408 so binary distributions allow you to install them without having a Haskell compiler.)
411 \subsection{Bundle structure}
413 Binary distributions come in ``bundles,''\index{bundles of binary stuff}
414 one bundle per file called \tr{<bundle>-<platform>.tar.gz}.
415 (See Section~\ref{port-info} for what a platform is.)
416 Suppose that you untar a binary-distribution bundle, thus:
418 % cd /your/scratch/space
419 % gunzip < ghc-2.02-sun-sparc-solaris2.tar.gz | tar xvf -
421 Then you should find a single directory, @fptools@, with the following
424 \item[@Makefile.in@] the raw material from which the @Makefile@ will be made (\sectionref{sect_install}).
425 \item[@configure@] the configuration script (\sectionref{sect_install}).
426 \item[@README@] Contains this file summary.
427 \item[@INSTALL@] Contains this description of how to install the bundle.
428 \item[@ANNOUNCE-<bundle>@] The announcement message for the bundle.
429 \item[@NEWS-<bundle>@] release notes for the bundle -- a longer version of @ANNOUNCE@.
430 \item[@bin/<platform>/@] contains platform-specific executable files to be invoked
431 directly by the user. These are the files that must end up in your path.
432 \item[@lib/<platform>@] contains platform-specific support files for the installation.
433 Typically there is a subdirectory for each @fptools@ project, whose name is
434 the name of the project with its version number.
435 For example, for GHC 2.02 there would be a sub-directory @ghc-2.02/@.
437 These sub-directories have the following general structure:
439 \item[@libHS.a@ etc:] supporting library archives.
440 \item[@ghc-iface.prl@ etc:] support scripts.
441 \item[@import/@] Interface files (@.hi@) for the prelude.
442 \item[@include/@] A few C @#include@ files.
445 \item[@share/@] contains platform-independent support files for the installation.
446 Again, there is a sub-directory for each @fptools@ project.
448 \item[@info/@] contains Emacs info documentation files (one sub-directory per project).
449 \item[@html/@] contains HTML documentation files (one sub-directory per project).
450 \item[@man/@] contains Unix manual pages.
452 This structure is designed so that you can unpack multiple bundles (including
453 ones from different releases or platforms) into a single @fptools@ directory:
455 % cd /your/scratch/space
456 % gunzip < ghc-2.02-sun-sparc-solaris2.tar.gz | tar xvf -
457 % gunzip < happy-1.09-sun-sparc-sunos4.tar.gz | tar xvf -
459 When you do multiple unpacks like this, the top level @Makefile@, @README@,
460 and @INSTALL@ get overwritten each time. That's fine -- they should be the same.
461 Likewise, the @ANNOUNCE-<bundle>@ and @NEWS-<bundle>@ files will be duplicated
462 across multiple platforms, so they will be harmlessly overwritten when you do
464 Finally, the @share/@ stuff will get harmlessly overwritten when you do multiple
465 unpacks for one bundle on different platforms.
467 \subsection[sect_install]{Installing}
469 OK, so let's assume that you have unpacked your chosen bundles into
470 a scratch directory @fptools@. What next? Well, you will at least need
471 to run the @configure@ script by changing your directory to @fptools@.
472 That should convert @Makefile.in@ to @Makefile@.
474 You can now either start using the tools {\em in-situ} without going
475 through any installation process, just type @make in-place@ to set the
476 tools up for this (you have to be in the @fptools@ directory for
477 this). You'll also want to add the path which @make@ will now echo to
478 your @PATH@ environment variable. This option is useful if you simply want
479 to try out the package and/or you don't have the necessary priviledges (or
480 inclination) to properly install the tools locally. Note that if you
481 do decide to install the package `properly' at a later date, you have
482 to go through the installation steps that follows.
484 To install an @fptools@ package, you'll have to do the following:
487 \item Edit the @Makefile@ and check the settings of the following variables:
489 \item[@platform@] the platform you are going to install for.
490 \item[@bindir@] the directory in which to install user-invokable binaries.
491 \item[@libdir@] the directory in which to install platform-dependent support files.
492 \item[@datadir@] the directory in which to install platform-independent support files.
493 \item[@infodir@] the directory in which to install Emacs info files.
494 \item[@htmldir@] the directory in which to install HTML documentation.
495 \item[@dvidir@] the directory in which to install DVI documentation.
497 The values for these variables can be set through invocation of the
498 @configure@ script that comes with the distribution, but doing an optical
499 diff to see if the values match your expectations is always a Good Idea.
501 {\em Instead of running @configure@, it is perfectly OK to copy
502 @Makefile.in@ to @Makefile@ and set all these variables directly
503 yourself. But do it right!}
505 \item Run @make install@. This {\em should} work with ordinary Unix
506 @make@ -- no need for fancy stuff like GNU @make@.
508 \item \tr{rehash} (t?csh users), so your shell will see the new stuff
509 in your bin directory.
512 Once done, test your ``installation'' as suggested in
513 \sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you
514 can see exactly what pathnames it's using.
516 If things don't work as expected, check the list of know pitfalls
517 \sectionref{build-pitfalls}.
520 When installing the user-invokable binaries, this installation
521 procedure will install, say, @GHC@ version 2.02 as @ghc-2.02@. It
522 will also make a link (in the binary installation directory) from
523 @ghc@ to @ghc-2.02@. If you install multiple versions of GHC then the
524 last one ``wins'', and ``@ghc@'' will invoke the last one installed.
525 You can change this manually if you want. But regardless, @ghc-2.02@
526 should always invoke @GHC@ version 2.02.
528 \subsection{What bundles there are}
530 There are plenty of ``non-basic'' GHC bundles. The files for them are
531 called \tr{ghc-2.04-<bundle>-<platform>.tar.gz}, where the
532 \tr{<platform>} is as above, and \tr{<bundle>} is one of these:
534 \item[\tr{prof}:] Profiling with cost-centres. You probably want this.
536 \item[\tr{conc}:] Concurrent Haskell features. You may want this.
538 \item[\tr{par}:] Parallel Haskell features (sits on top of PVM).
539 You'll want this if you're into that kind of thing.
541 \item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator
542 (hmm... mainly for implementors).
544 \item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed
545 information about ``what happened when I ran this program''---really
548 \item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell.
550 \item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell.
553 One likely scenario is that you will grab {\em three} binary
554 bundles---basic, profiling, and concurrent.
558 %************************************************************************
560 \subsection[GHC_test]{Test that GHC seems to be working}
561 \index{testing a new GHC}
563 %************************************************************************
565 The way to do this is, of course, to compile and run {\em this} program
566 (in a file \tr{Main.hs}):
568 main = putStr "Hello, world!\n"
571 First, give yourself a convenient way to execute the driver script
572 \tr{ghc/driver/ghc}, perhaps something like...
574 % ln -s /local/src/ghc-2.04/ghc/driver/ghc ~/bin/alpha/ghc
578 Compile the program, using the \tr{-v} (verbose) flag to verify that
579 libraries, etc., are being found properly:
581 % ghc -v -o hello Main.hs
590 Some simple-but-profitable tests are to compile and run the
591 notorious \tr{nfib} program, using different numeric types. Start
592 with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float},
593 \tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code
594 for this is distributed in \tr{ghc/misc/examples/nfib/}.
596 For more information on how to ``drive'' GHC,
597 either do \tr{ghc -help} or consult the User's Guide (distributed in
598 \tr{ghc/docs/users_guide}).
601 %************************************************************************
603 \section[Pre-supposed]{Installing pre-supposed utilities}
604 \index{pre-supposed utilities}
605 \index{utilities, pre-supposed}
607 %************************************************************************
609 \label{sect_std-utils}
611 Here are the gory details about some utility programs you may need;
612 \tr{perl} and \tr{gcc} are the only important ones. (PVM is important
613 if you're going for Parallel Haskell.) The \tr{configure} script will
614 tell you if you are missing something.
618 \index{pre-supposed: Perl}
619 \index{Perl, pre-supposed}
620 {\em You have to have Perl to proceed!} Perl is a language quite good
621 for doing shell-scripty tasks that involve lots of text processing.
622 It is pretty easy to install.
624 Perl~5 is the current version; GHC should be Perl~4 friendly though.
625 For Win32 platforms, Perl~5 is recommended, we even strongly suggest
626 you pick up a port of Perl~5 for \tr{cygwin32}, as the common
627 Hip/ActiveWare port of Perl is not Cool Enough for our purposes.
629 Perl should be put somewhere so that it can be invoked by the \tr{#!}
630 script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred;
631 we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should
632 be less than 32 characters long.
634 \item[GNU C (\tr{gcc}):]
635 \index{pre-supposed: GCC (GNU C compiler)}
636 \index{GCC (GNU C compiler), pre-supposed}
637 The current version is 2.7.2.
639 If your GCC dies with ``internal error'' on some GHC source file,
640 please let us know, so we can report it and get things improved.
641 (Exception: on \tr{iX86} boxes---you may need to fiddle with GHC's
642 \tr{-monly-N-regs} option; ask if confused...)
644 \item[PVM version 3:]
645 \index{pre-supposed: PVM3 (Parallel Virtual Machine)}
646 \index{PVM3 (Parallel Virtual Machine), pre-supposed}
647 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
648 run. (You only need this if you plan to run Parallel Haskell.
649 Concurent Haskell, which runs concurrent threads on a uniprocessor
651 Underneath PVM, you can have (for example) a network of
652 workstations (slow) or a multiprocessor box (faster).
654 The current version of PVM is 3.3.11; we use 3.3.7. It is readily
655 available on the net; I think I got it from \tr{research.att.com}, in
658 A PVM installation is slightly quirky, but easy to do. Just follow
659 the \tr{Readme} instructions.
661 \item[\tr{xargs} on Solaris2:]
662 \index{xargs, presupposed (Solaris only)}
663 \index{Solaris: alternative xargs}
664 The GHC libraries are put together with something like:
666 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
668 Unfortunately the Solaris \tr{xargs} (the shell-script equivalent
669 of \tr{map}) only ``bites off'' the \tr{.o} files a few at a
670 time---with near-infinite rebuilding of the symbol table in
673 The best solution is to install a sane \tr{xargs} from the GNU
674 findutils distribution. You can unpack, build, and install the GNU
675 version in the time the Solaris \tr{xargs} mangles just one GHC
678 \item[\tr{bash} (Parallel Haskell only):]
679 \index{bash, presupposed (Parallel Haskell only)}
680 Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles''
681 to PostScript, is written in Bash (GNU's Bourne Again shell).
682 This bug will be fixed (someday).
685 \index{pre-supposed: makeindex}
686 \index{makeindex, pre-supposed}
687 You won't need this unless you are re-making our documents. Makeindex
688 normally comes with a \TeX{} distribution, but if not, we can provide
689 the latest and greatest.
692 \index{pre-supposed: tgrind}
693 \index{tgrind, pre-supposed}
694 This is required only if you remake lots of our documents {\em and}
695 you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate
696 programming), to do ``fancy'' typesetting of your code. {\em
700 \index{pre-supposed: flex}
701 \index{flex, pre-supposed}
702 This is a quite-a-bit-better-than-Lex lexer. Used in the
703 literate-programming stuff. You won't need it unless you're hacking
704 on some of our more obscure stuff.
707 \index{pre-supposed: non-worthless Yacc}
708 \index{Yacc, pre-supposed}
709 If you mess with the Haskell parser, you'll need a Yacc that can cope.
710 The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK;
711 Berkeley yacc, \tr{byacc}, is not OK.
714 \index{pre-supposed: sed}
715 \index{sed, pre-supposed}
716 You need a working @sed@ if you are going to build from sources.
717 The build-configuration stuff needs it.
718 GNU sed version 2.0.4 is no good! It has a bug in it that is tickled
719 by the build-configuration. 2.0.5 is ok. Others are probably ok too
720 (assuming we don't create too elaborate configure scripts..)
723 Two @fptools@ projects are worth a quick note at this point, because
724 they are useful for all the others:
726 \item @glafp-utils@ contains several utilities which aren't
727 particularly Glasgow-ish, but Occasionally Indispensable. Like
728 @lndir@ for creating symbolic link trees.
730 \item @literate@ contains the Glasgow-built tools for generating
731 documentation. (The unoriginal idea is to be able to generate @latex@, @info@,
732 and program code from a single source file.) To get anywhere you'll
733 need at least @lit2pgm@, either from the @literate@ project, or
734 because it's already installed on your system.
739 %************************************************************************
741 \section{Building from source}
743 %************************************************************************
745 You've been rash enough to want to build some of
746 the Glasgow Functional Programming tools (GHC, Happy,
747 nofib, etc) from source. You've slurped the source,
748 from the CVS repository or from a source distribution, and
749 now you're sitting looking at a huge mound of bits, wondering
752 Gingerly, you type @make all@. Wrong already!
754 This rest of this guide is intended for duffers like me, who aren't really
755 interested in Makefiles and systems configurations, but who need
756 a mental model of the interlocking pieces so that they can
757 make them work, extend them consistently when adding new
758 software, and lay hands on them gently when they don't work.
760 \subsection{Your source tree}
763 The source code is held in your {\em source tree}.
764 The root directory of your source tree {\em must}
765 contain the following directories and files:
767 \item @Makefile@: the root Makefile.
768 \item @mk/@: the directory that contains the
769 main Makefile code, shared by all the
771 \item @configure.in@, @config.sub@, @config.guess@:
772 these files support the configuration process.
775 All the other directories are individual {\em projects} of the
776 @fptools@ system --- for example, the Glasgow Haskell Compiler (@ghc@),
777 the Happy parser generator (@happy@), the @nofib@ benchmark suite,
779 You can have zero or more of these. Needless to say, some of them
780 are needed to build others. For example, you need @happy@ to build
781 @ghc@. You can either grab @happy@ too, or else you can use
782 a version of @happy@ that's already installed on your system, or
783 grab a binary distribution of @happy@ and install it.
785 The important thing to remember is that even if you want only
786 one project (@happy@, say), you must have a source tree
787 whose root directory contains @Makefile@,
788 @mk/@, @configure.in@, and the project(s) you
789 want (@happy/@ in this case). You cannot get by with
790 just the @happy/@ directory.
792 \subsection{Build trees}
794 While you can build a system in the source tree, we don't recommend it.
795 We often want to build multiple versions of our software
796 for different architectures, or with different options (e.g. profiling).
797 It's very desirable to share a single copy of the source code among
800 So for every source tree we have zero or more {\em build trees}. Each
801 build tree is initially an exact copy of the source tree, except that
802 each file is a symbolic link to the source file, rather than being a
803 copy of the source file. There are ``standard'' Unix utilities that
804 make such copies, so standard that they go by different names:
805 @lndir@, @mkshadowdir@ are two (If you don't have either, the source
806 distribution includes sources for the \tr{X11} \tr{lndir} --- check
807 out \tr{fptools/glafp-utils/lndir} ).
809 The build tree does not need to be anywhere near the source tree in
810 the file system. Indeed, one advantage of separating the build tree
811 from the source is that the build tree can be placed in a
812 non-backed-up partition, saving your systems support people from
813 backing up untold megabytes of easily-regenerated, and
814 rapidly-changing, gubbins. The golden rule is that (with a single
815 exception -- Section~\ref{sect_build-config}) {\em absolutely
816 everything in the build tree is either a symbolic link to the source
817 tree, or else is mechanically generated}. It should be perfectly OK
818 for your build tree to vanish overnight; an hour or two compiling and
819 you're on the road again.
821 You need to be a bit careful, though, that any new files you create
822 (if you do any development work) are in the source tree, not a build tree!
824 Remember, that the source files in the build tree are {\em symbolic
825 links} to the files in the source tree. (The build tree soon
826 accumulates lots of built files like @Foo.o@, as well.) You can {\em
827 delete} a source file from the build tree without affecting the source
828 tree (though it's an odd thing to do). On the other hand, if you {\em
829 edit} a source file from the build tree, you'll edit the source-tree
830 file directly. (You can set up Emacs so that if you edit a source
831 file from the build tree, Emacs will silently create an edited copy of
832 the source file in the build tree, leaving the source file unchanged;
833 but the danger is that you think you've edited the source file whereas
834 actually all you've done is edit the build-tree copy. More commonly
835 you do want to edit the source file.)
837 Like the source tree, the top level of your build tree must (a linked
838 copy of) the root directory of the @fptools@ suite. Inside Makefiles,
839 the root of your build tree is called @$(FPTOOLS_TOP)@. In the rest
840 of this document path names are relative to @$(FPTOOLS_TOP)@ unless
841 otherwise stated. For example, the file @ghc/mk/target.mk@ is
842 actually @$(FPTOOLS_TOP)/ghc/mk/target.mk@.
845 \subsection{Getting the build you want}
846 \label{sect_build-config}
848 When you build @fptools@ you will be compiling code on a particular
849 {\em host platform}, to run on a particular {\em target platform}
850 (usually the same as the host platform)\index{platform}. The
851 difficulty is that there are minor differences between different
852 platforms; minor, but enough that the code needs to be a bit different
853 for each. There are some big differences too: for a different
854 architecture we need to build GHC with a different native-code
857 There are also knobs you can turn to control how the @fptools@
858 software is built. For example, you might want to build GHC optimised
859 (so that it runs fast) or unoptimised (so that you can compile it fast
860 after you've modified it. Or, you might want to compile it with
861 debugging on (so that extra consistency-checking code gets included)
864 All of this stuff is called the {\em configuration} of your build.
865 You set the configuration using an exciting three-step process.
867 \item[Step 1: get ready for configuration.]
868 Change directory to @$(FPTOOLS)@ and issue the following two commands (with no arguments):
870 \item @autoconf@. This GNU program
871 converts @$(FPTOOLS)/configure.in@ to a shell script
872 called @$(FPTOOLS)/configure@.
874 \item @autoheader@. This second GNU program converts
875 @$(FPTOOLS)/configure.in@ to @$(FPTOOLS)/mk/config.h.in@.
877 Both these steps are completely platform-independent; they just mean
878 that the human-written file (@configure.in@) can be short, although
879 the resulting shell script, @configure@, and @mk/config.h.in@, are long.
881 In case you don't have @autoconf@ and @autoheader@ we distribute
882 the results, @configure@, and @mk/config.h.in@, with the source distribution.
883 They aren't kept in the repository, though.
885 \item[Step 2: system configuration.]
886 Runs the newly-created @configure@ script, thus:
890 @configure@'s mission
891 is to scurry round your computer working out what architecture it has,
892 what operating system, whether it has the @vfork@ system call,
893 where @yacc@ is kept, whether @gcc@ is available, where various
894 obscure @#include@ files are, whether it's a leap year, and
895 what the systems manager had for lunch.
896 It communicates these snippets of information in two ways:
898 \item It translates @mk/config.mk.in@ to @mk/config.mk@,
899 substituting for things between ``{\tt @@@@}'' brackets. So,
900 ``{\tt @@HaveGcc@@}'' will be replaced by ``@YES@'' or ``@NO@''
901 depending on what @configure@ finds.
902 @mk/config.mk@ is included by every Makefile (directly or indirectly),
903 so the configuration information is thereby communicated to
906 \item It translates @mk/config.h.in@ to @mk/config.h@.
907 The latter is @#include@d by various C programs, which
908 can thereby make use of configuration information.
912 \item[Step 3: build configuration.] Next, you say how this build
913 of @fptools@ is to differ from the standard defaults by creating a new
915 {\em in the build tree}. This file is the one and only
916 file you edit in the build tree, precisely because it says how
917 this build differs from the source. (Just in case your build tree
918 does die, you might want to keep a private directory of @build.mk@ files,
919 and use a symbolic link in each build tree to point to the appropriate one.)
920 So @mk/build.mk@ never
921 exists in the source tree --- you create one in each build tree
922 from the template. We'll discuss what to put in it shortly.
924 And that's it for configuration. Simple, eh?
926 What do you put in your build-specific configuration
927 file @mk/build.mk@? {\em For almost all purposes all you will do is
928 put make variable definitions that override those in @mk/config.mk.in@}.
929 The whole point of @mk/config.mk.in@ --- and its derived
930 counterpart @mk/config.mk@ --- is to define the build configuration. It is heavily
931 commented, as you will see if you look at it.
932 So generally, what you do is edit @mk/config.mk.in@ (read-only), and add definitions
933 in @mk/build.mk@ that override any of the @config.mk@ definitions that you
934 want to change. (The override occurs because the main boilerplate file,
935 @mk/boilerplate.mk@, includes @build.mk@ after @config.mk@.)
937 For example, @config.mk.in@ contains the definition:
939 ProjectsToBuild = glafp-utils literate ghc hslibs
941 The accompanying comment explains that this is the list of enabled
942 projects; that is, if (after configuring) you type @gmake all@
943 in @FPTOOLS_TOP@ three specified projects will be made.
944 If you want to add @happy@, you can add this line to @build.mk@:
946 ProjectsToBuild += happy
950 ProjectsToBuild = glafp-utils literate ghc hslibs happy
952 (GNU @make@ allows existing definitions to have new text appended using
953 the ``@+=@'' operator, which is quite a convenient feature.)
955 When reading @config.mk.in@, remember that anything between ``{\tt @@...@@}'' signs
956 is going to be substituted by @configure@ later. You {\em can} override
957 the resulting definition if you want,
958 but you need to be a bit surer what you are doing.
959 For example, there's a line that says:
963 This defines the Make variables @YACC@ to the pathname for a Yacc that
964 @configure@ finds somewhere. If you have your own pet Yacc you want
965 to use instead, that's fine. Just add this line to @mk/build.mk@:
969 You do not {\em have} to have a @mk/build.mk@ file at all; if you don't,
970 you'll get all the default settings from @mk/config.mk.in@.
973 \subsection{The story so far}
975 Let's summarise the steps you need to carry to get yourself
976 a fully-configured build tree from scratch.
979 \item Get your source tree from somewhere (CVS repository or
980 source distribution). Say you call the root directory
981 @myfptools@ (it does not have to be called @fptools@).
982 Make sure that you have the essential files (see Section~\ref{source-tree}).
984 \item Use @lndir@ or @mkshadowdir@ to create a build tree.
987 mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
989 You probably want to give the build tree a name that
990 suggests its main defining characteristic (in your mind at least),
991 in case you later add others.
993 \item Change directory to the build tree. Everything is going
996 cd /scratch/joe-bloggs/myfptools-sun4
998 \item Prepare for system configuration:
1003 (You can skip this step if you are starting from a source distribution,
1004 and you already have @configure@ and @mk/config.h.in@.)
1006 \item Do system configuration:
1011 \item Create the file @mk/build.mk@,
1012 adding definitions for your desired configuration options.
1017 You can make subsequent changes to @mk/build.mk@ as often
1018 as you like. You do not have to run any further configuration
1019 programs to make these changes take effect.
1020 In theory you should, however, say @gmake clean@, @gmake all@,
1021 because configuration option changes could affect anything --- but in practice you are likely to know what's affected.
1023 \subsection{Making things}
1025 At this point you have made yourself a fully-configured build tree,
1026 so you are ready to start building real things.
1028 The first thing you need to know is that
1029 {\em you must use GNU @make@, usually called @gmake@, not standard Unix @make@}.
1030 If you use standard Unix @make@ you will get all sorts of error messages
1031 (but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities
1034 \subsection[sect_standard-targets]{Standard targets}
1036 In any directory you should be able to make the following:
1038 \item[@boot@:] does the one-off preparation required to get ready
1039 for the real work. Notably, it does @gmake depend@ in all directories
1040 that contain programs. But @boot@ does more. For example, you can't
1041 do @gmake depend@ in a directory of C program until you have converted
1042 the literate @.lh@ header files into standard @.h@ header files.
1043 Similarly, you convert a literate file to illiterate form until you
1044 have built the @literate@ tools. @boot@ takes care of these
1045 inter-directory dependencies.
1047 You should say @gmake boot@ right after configuring your build tree,
1048 but note that this is a one-off, i.e., there's no need to re-do
1049 @gmake boot@ if you should re-configure your build tree at a later
1050 stage (no harm caused if you do though).
1052 \item[@all@:] makes all the final target(s) for this Makefile.
1053 Depending on which directory you are in a ``final target''
1054 may be an executable program, a library archive, a shell script,
1055 or a Postscript file.
1056 Typing @gmake@ alone is generally the same as typing @gmake all@.
1058 \item[@install@:] installs the things built by @all@. Where does it
1059 install them? That is specified by @mk/config.mk.in@; you can
1060 override it in @mk/build.mk@.
1062 \item[@uninstall@:] reverses the effect of @install@.
1064 \item[@clean@:] remove all easily-rebuilt files.
1066 \item[@veryclean@:] remove all files that can be rebuilt at all.
1067 There's a danger here that you may remove a file that needs a more
1069 utility to rebuild it (especially if you started from a source
1072 \item[@check@:] run the test suite.
1074 All of these standard targets
1075 automatically recurse into sub-directories.
1076 Certain other standard targets do not:
1078 \item[@configure@:] is only available in the root directory @$(FPTOOLS)@;
1079 it has been discussed in Section~\ref{sect_build-config}.
1081 \item[@depend@:] make a @.depend@ file in each directory that needs
1082 it. This @.depend@ file contains mechanically-generated dependency
1083 information; for example, suppose a directory contains a Haskell
1084 source module @Foo.lhs@ which imports another module @Baz@.
1085 Then the generated @.depend@ file will contain the dependency:
1089 which says that the object file @Foo.o@ depends on the interface
1090 file @Baz.hi@ generated by compiling module @Baz@.
1091 The @.depend@ file is automatically included by every Makefile.
1093 \item[@binary-dist@:] make a binary distribution.
1095 \item[@dist@:] make a source distribution.
1098 \subsection{Other targets}
1100 Most @Makefiles@ have targets other than these. You can find
1101 this out by looking in the @Makefile@ itself.
1106 %************************************************************************
1108 \section{The @Makefile@ architecture}
1110 %************************************************************************
1113 @make@ is great if everything works --- you type @gmake install@ and, lo,
1114 the right things get compiled and installed in the right places.
1115 Our goal is to make this happen often, but somehow it often doesn't;
1117 some wierd error message eventually emerges from the bowels of a directory
1118 you didn't know existed.
1120 The purpose of this section is to give you a road-map to help you figure
1121 out what is going right and what is going wrong.
1123 \subsection{A small project}
1125 To get started, let us look at the @Makefile@ for an imaginary small
1126 @fptools@ project, @small@. Each project in @fptools@ has its own
1127 directory in @FPTOOLS_TOP@, so the @small@ project will have its own
1128 directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there
1129 will be a @Makefile@, looking something like this:
1131 # Makefile for fptools project "small"
1134 include $(TOP)/mk/boilerplate.mk
1136 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1139 include $(TOP)/target.mk
1141 This @Makefile@ has three sections:
1143 \item The first section includes\footnote{One of the
1144 most important features of GNU @make@ that we use is the ability
1145 for a @Makefile@ to include another named file, very like @cpp@'s @#include@ directive.}
1146 a file of ``boilerplate'' code from the
1147 level above (which in this case will be @FPTOOLS_TOP/mk/boilerplate.mk@).
1148 As its name suggests, @boilerplate.mk@ consists of a large quantity of standard
1149 @Makefile@ code. We discuss this boilerplate in more detail in Section~\ref{sect_boiler}.
1151 Before the @include@ statement, you must define the @make@ variable
1152 @TOP@ to be the directory containing the @mk@ directory in which
1153 the @boilerplate.mk@ file is.
1154 It is {\em not} OK to simply say
1156 include ../mk/boilerplate.mk # NO NO NO
1158 Why? Because the @boilerplate.mk@ file needs to know where it is,
1159 so that it can, in turn, @include@ other files.
1160 (Unfortunately, when an @include@d file does an
1161 @include@, the filename is treated
1162 relative to the directory in which @gmake@ is being run, not
1163 the directory in which the @included@ sits.)
1165 {\em every file @foo.mk@
1166 assumes that @$(TOP)/mk/foo.mk@ refers to itself.}
1167 It is up to the @Makefile@ doing the @include@ to ensure this
1170 Files intended for inclusion in other @Makefile@s are written to have
1171 the following property:
1172 {\em after @foo.mk@ is @include@d, it leaves @TOP@ containing the same
1173 value as it had just before the @include@ statement}.
1174 In our example, this invariant guarantees that the @include@
1175 for @target.mk@ will look in the same directory as that for
1178 \item The second section
1179 defines the following standard @make@ variables: @SRCS@ (the source files from
1180 which is to be built), and @HS_PROG@ (the
1181 executable binary to be built).
1182 We will discuss in more detail what the ``standard variables'' are,
1183 and how they affect what happens, in Section~\ref{sect_targets}.
1185 The definition for @SRCS@ uses the useful GNU @make@
1186 construct @$(wildcard@~$pat$@)@, which expands to a list of all the
1187 files matching the pattern $pat$ in the current directory.
1188 In this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@ files
1189 in the directory. (Let's suppose there is one of each, @Foo.lhs@
1192 \item The last section includes a second file of standard code,
1193 called @target.mk@. It contains the rules that tell @gmake@
1194 how to make the standard targets
1195 (Section~\ref{sect_standard-targets}).
1196 Why, you ask, can't this standard code
1197 be part of @boilerplate.mk@? Good question.
1198 We discuss the reason later, in Section~\ref{sect_boiler-arch}.
1200 You do not {\em have} to @include@ the @target.mk@ file. Instead,
1201 you can write rules of your own for all the standard targets.
1202 Usually, though, you will find quite a big payoff from using
1204 @target.mk@; the price tag is that you have to understand
1205 what canned rules get enabled, and what they do (Section~\ref{sect_targets}).
1208 In our example @Makefile@, most of the work is done
1209 by the two @include@d files. When you say @gmake all@,
1210 the following things happen:
1212 \item @gmake@ figures out that the object files are @Foo.o@ and @Baz.o@.
1213 \item It uses a boilerplate pattern rule to compile
1214 @Foo.lhs@ to @Foo.o@ using
1215 a Haskell compiler. (Which one? That is set in the build configuration.)
1216 \item It uses another standard pattern rule to compile @Baz.c@ to @Baz.o@,
1217 using a C compiler. (Ditto.)
1218 \item It links the resulting @.o@ files together to make @small@,
1219 using the Haskell compiler to do the link step. (Why not use @ld@? Because
1220 the Haskell compiler knows what standard librarise to link in. How did @gmake@
1221 know to use the Haskell compiler to do the link, rather than the C compiler?
1222 Because we set the variable @HS_PROG@ rather than @C_PROG@.)
1224 All @Makefile@s should follow the above three-section format.
1226 \subsection{A larger project}
1228 Larger projects are usually structured into a nummber of sub-directories,
1229 each of which has its own @Makefile@. (In very large projects, this
1230 sub-structure might be iterated recursively, though that is rare.)
1231 To give you the idea, here's part of the directory structure for
1232 the (rather large) @ghc@ project:
1243 ...source files for documentation...
1247 ...source files for driver...
1251 parser/...source files for parser...
1252 renamer/...source files for renamer...
1255 The sub-directories @docs@, @driver@, @compiler@, and so on, each contains
1256 a sub-component of @ghc@, and each has its own @Makefile@.
1257 There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@.
1258 It does most of its work by recursively invoking @gmake@
1259 on the @Makefile@s in the sub-directories.
1260 We say that @ghc/Makefile@ is a {\em non-leaf @Makefile@},
1261 because it does little except organise its children, while the @Makefile@s
1262 in the sub-directories are all {\em leaf @Makefile@s}. (In principle
1263 the sub-directories might themselves contain a non-leaf @Makefile@ and
1264 several sub-sub-directories, but that does not happen in @ghc@.)
1266 The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even
1267 though the @ghc/compiler@ has sub-directories, because these sub-directories
1268 do not themselves have @Makefile@ in them. They are just used to structure
1269 the collection of modules that make up @ghc@, but all are managed by the
1270 single @Makefile@ in @ghc/compiler@.
1272 You will notice that @ghc/@ also contains a directory @ghc/mk/@.
1273 It contains @ghc@-specific @Makefile@ boilerplate code.
1276 \item @ghc/mk/boilerplate.mk@ is included at the top of @ghc/Makefile@,
1277 and of all the leaf @Makefile@s in the sub-directories.
1278 It in turn @include@s the main boilerplate file @mk/boilerplate.mk@.
1280 \item @ghc/mk/target.mk@ is @include@d at the bottom of @ghc/Makefile@,
1281 and of all the leaf @Makefiles@ in the sub-directories.
1282 It in turn @include@s the file @mk/target.mk@.
1284 So these two files are the place to look for @ghc@-wide customisation
1285 of the standard boilerplate.
1289 \subsection{Boilerplate architecture}
1290 \label{sect_boiler-arch}
1292 Every @Makefile@ includes a @boilerplate.mk@ file at the top,
1293 and @target.mk@ file at the bottom. In this section we discuss
1294 what is in these files, and why there have to be two of them.
1297 \item @boilerplate.mk@ consists of:
1299 \item {\em Definitions of millions of @make@ variables} that collectively
1300 specify the build configuration. Examples: @HC_OPTS@, the options to
1301 feed to the Haskell compiler; @NoFibSubDirs@, the sub-directories to
1302 enable within the @nofib@ project; @GhcWithHc@, the name of the
1303 Haskell compiler to use when compiling @GHC@ in the @ghc@ project.
1304 \item {\em Standard pattern rules} that tell @gmake@ how to construct
1305 one file from another.
1307 @boilerplate.mk@ needs to be @include@d at the {\em top} of each
1308 @Makefile@, so that the
1309 user can replace the boilerplate definitions or pattern rules by simply
1310 giving a new definition or pattern rule in the @Makefile@. @gmake@ simply
1311 takes the last definition as the definitive one.
1313 Instead of {\em replacing} boilerplate definitions, it is also quite
1314 common to {\em augment} them. For example, a @Makefile@ might say:
1318 thereby adding ``@-O@'' to the end of @SRC_HC_OPTS@.
1320 \item @target.mk@ contains @make@ rules for the standard targets described
1321 in Section~\ref{sect_standard-targets}.
1322 These rules are selectively included, depending on the setting of
1323 certain @make@ variables. These variables are usually set in the middle
1324 section of the @Makefile@ between the two @include@s.
1326 @target.mk@ must be included at the end (rather than being part of @boilerplate.mk@)
1327 for several tiresome reasons:
1329 \item @gmake@ commits target and dependency lists earlier than it should.
1330 For example, @target.mk@ has a rule that looks like this:
1332 $(HS_PROG) : $(OBJS)
1333 $(HC) $(LD_OPTS) $< -o $@
1335 If this rule was in @boilerplate.mk@ then @$(HS_PROG)@ and @$(OBJS)@
1336 would not have their final values at the moment @gmake@ encountered the
1337 rule. Alas, @gmake@ takes a snapshot of their current values, and
1338 wires that snapshot into the rule.
1339 (In contrast, the commands executed when the rule ``fires'' are
1340 only substituted at the moment of firing.)
1341 So, the rule must follow the definitions given in the @Makefile@ itself.
1343 \item Unlike pattern rules, ordinary rules cannot be overriden or
1344 replaced by subsequent rules for the same target (at least not without an
1345 error message). Including ordinary rules in @boilerplate.mk@ would
1346 prevent the user from writing rules for specific targets in specific cases.
1348 \item There are a couple of other reasons I've forgotten, but it doesn't
1353 \subsection{The main @mk/boilerplate.mk@ file}
1356 If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find that
1357 it consists of the following sections, each held in a separate file:
1359 \item[@config.mk@] is the build configuration file we discussed at length
1360 in Section~\ref{sect_build-config}.
1362 \item[@paths.mk@] defines @make@ variables for pathnames and file
1363 lists. In particular, it gives definitions for:
1365 \item[@SRCS@:] all source files in the current directory.
1366 \item[@HS_SRCS@:] all Haskell source files in the current directory.
1367 It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value
1368 @HS_SRCS@ will follow suit.
1369 \item[@C_SRCS@:] similarly for C source files.
1370 \item[@HS_OBJS@:] the @.o@ files derived from @$(HS_SRCS)@.
1371 \item[@C_OBJS@:] similarly for @$(C_SRCS)@.
1372 \item[@OBJS@:] the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@.
1374 Any or all of these definitions can easily be overriden by giving new
1375 definitions in your @Makefile@. For example,
1376 if there are things in the current directory that look like source files
1377 but aren't, then you'll need to set @SRCS@ manually in your @Makefile@.
1378 The other definitions will then work from this new definition.
1380 What, exactly, does @paths.mk@ consider a ``source file'' to be.
1381 It's based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc),
1382 but this is the kind of detail that changes
1383 more rapidly, so rather than enumerate the source suffices here the best thing
1384 to do is to look in @paths.mk@.
1386 \item[@opts.mk@] defines @make@ variables for option strings to
1387 pass to each program. For example, it defines @HC_OPTS@, the
1388 option strings to pass to the Haskell compiler. See \sectionref{sect_suffix}.
1390 \item[@suffix.mk@] defines standard pattern rules -- see \sectionref{sect_suffix}
1392 Any of the variables and pattern rules defined by the boilerplate file
1393 can easily be overridden in any particular @Makefile@, because
1394 the boilerplace @include@ comes first. Definitions after this
1395 @include@ directive simply override the default ones in @boilerplate.mk@.
1397 \subsection[sect_suffix]{Pattern rules and options}
1399 The file @suffix.mk@ defines standard {\em pattern rules} that say how to build one kind
1400 of file from another, for example, how to build a @.o@ file from a @.c@ file.
1401 (GNU @make@'s {\em pattern rules} are more powerful and easier to use than
1402 Unix @make@'s {\em suffix rules}.)
1404 Almost all the rules look something like this:
1408 $(CC) $(CC_OPTS) -c $< -o $@
1410 Here's how to understand the rule. It says that $something@.o@$ (say @Foo.o@)
1411 can be built from $something@.c@$ (@Foo.c@), by invoking the C compiler
1412 (path name held in @$(CC)@), passing to it the options @$(CC_OPTS)@ and the rule's
1414 file of the rule @$<@ (@Foo.c@ in this case), and putting the result in
1415 the rule's target @$@@@ (@Foo.o@ in this case).
1417 Every program is held in a @make@ variable defined in @mk/config.mk@ --- look in @mk/config.mk@ for
1418 the complete list. One important one is the Haskell compiler, which is called @$(HC)@.
1420 Every programs options are are held in a @make@ variables called @<prog>_OPTS@.
1421 the @<prog>_OPTS@ variables are defined in @mk/opts.mk@. Almost all of them are defined
1424 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
1426 The four variables from which @CC_OPTS@ is built have the following meaning:
1428 \item[@SRC_CC_OPTS@:] options passed to all C compilations.
1429 \item[@WAY_<way>_CC_OPTS@:] options passed to C compilations for way @<way>@. For example,
1430 @WAY_mp_CC_OPTS@ gives options to pass to the C compiler when compiling way @mp@.
1431 The variable @WAY_CC_OPTS@ holds options to pass to the C compiler when compiling the standard way.
1432 (Section~\ref{sect_ways} dicusses multi-way compilation.)
1433 \item[@<module>_CC_OPTS@:] options to pass to the C compiler that are specific to module @<module>@.
1434 For example, @SMap_CC_OPTS@ gives the specific options to pass to the C compiler when compiling
1436 \item[@EXTRA_CC_OPTS@:] extra options to pass to all C compilations. This is intended for command
1439 gmake libHS.a EXTRA_CC_OPTS="-v"
1444 \subsection{The main @mk/target.mk@ file}
1445 \label{sect_targets}
1447 @target.mk@ contains canned rules for all the standard targets described in
1448 Section~\ref{sect_standard-targets}. It is complicated by the fact
1449 that you don't want all of these rules to be active in every @Makefile@.
1450 Rather than have a plethora of tiny files which you can include selectively,
1451 there is a single file, @target.mk@, which selectively includes rules
1452 based on whether you have defined certain variables in your @Makefile@.
1453 This section explains what rules you get, what variables control them, and
1454 what the rules do. Hopefully, you will also get enough of an idea of what is supposed
1455 to happen that you can read and understand any wierd special cases yourself.
1458 \item{@HS_PROG@.} If @HS_PROG@ is defined, you get rules with the
1461 \item[@HS_PROG@] itself. This rule links @$(OBJS)@ with the Haskell
1462 runtime system to get an executable called @$(HS_PROG)@.
1463 \item[@install@] installs @$(HS_PROG)@ in @$(bindir)@ with the execute bit set.
1466 \item[@C_PROG@] is similar to @HS_PROG@, except that the link step
1467 links @$(C_OBJS)@ with the C runtime system.
1469 \item[@LIBRARY@] is similar to @HS_PROG@, except
1470 that it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@,
1471 and @install@ installs it in @$(libdir)@, with the execute bit not set.
1473 \item[@LIB_DATA@] ...
1474 \item[@LIB_EXEC@] ...
1476 \item[@HS_SRCS@, @C_SRCS@.] If @HS_SRCS@ is defined and non-empty, a rule for
1477 the target @depend@ is included, which generates dependency information for
1478 Haskell programs. Similarly for @C_SRCS@.
1481 All of these rules are ``double-colon'' rules, thus
1483 install :: $(HS_PROG)
1484 ...how to install it...
1486 GNU @make@ treats double-colon rules as separate entities. If there
1487 are several double-colon rules for the same target it takes each in turn
1488 and fires it if its dependencies say to do so. This means that you can,
1489 for example, define both @HS_PROG@ and @LIBRARY@, which will generate two
1490 rules for @install@. When you type @gmake install@ both rules will be fired,
1491 and both the program and the library will be installed, just as you wanted.
1493 \subsection{Recursion}
1494 \label{sect_subdirs}
1496 In leaf @Makefiles@ the variable @SUBDIRS@ is undefined. In non-leaf
1497 @Makefiles@, @SUBDIRS@ is set to the list of sub-directories that contain subordinate
1498 @Makefile@s. {\em It is up to you to set @SUBDIRS@ in the @Makefile@.}
1499 There is no automation here --- @SUBDIRS@ is too important automate.
1501 When @SUBDIRS@ is defined, @target.mk@ includes a rather neat rule for
1502 the standard targets (Section~\ref{sect_standard-targets}) that
1503 simply invokes @make@ recursively in each of the sub-directories.
1505 {\em These recursive invocations are guaranteed to occur in the order in
1506 which the list of directories is specified in @SUBDIRS@.} This guarantee can
1507 be important. For example, when you say @gmake boot@ it can be important
1508 that the recursive invocation of @make boot@ is done in one sub-directory (the include
1509 files, say) before another (the source files).
1510 Generally, put the most independent sub-directory first, and the most dependent
1513 \subsection{Way management}
1516 We sometimes want to build essentially the same system in several different
1517 ``ways''. For example, we want to build @ghc@'s @Prelude@ libraries with
1518 and without profiling, with and without concurrency, and so on, so that
1519 there is an appropriately-built library archive to link with when the user compiles
1521 It would be possible to have a completely separate build tree for each such ``way'',
1522 but it would be horribly bureaucratic, especially since often only parts of the
1523 build tree need to be constructed in multiple ways.
1525 Instead, the @template.mk@ contains some clever magic to allow you to build
1526 several versions of a system; and to control locally how many versions are built
1527 and how they differ. This section explains the magic.
1529 The files for a particular way are distinguished by munging the suffix.
1530 The ``normal way'' is always built, and its files have the standard suffices
1531 @.o@, @.hi@, and so on. In addition, you can build one or more extra ways,
1532 each distinguished by a {\em way tag}. The object files and interface files
1533 for one of these extra ways are distinguished by their suffix. For example,
1534 way @mp@ has files @.mp_o@ and @.mp_hi@. Library archives have their way
1535 tag the other side of the dot, for boring reasons; thus, @libHS_mp.a@.
1537 A @make@ variable called @way@ holds the current way tag. {\em @way@ is only ever
1538 set on the command line of a recursive invocation of @gmake@.} It is
1539 never set inside a @Makefile@. So it is a global constant for any one invocation
1540 of @gmake@. Two other @make@ variables, @way_@ and @_way@ are immediately derived
1541 from @$(way)@ and never altered. If @way@ is not set, then neither are @way_@
1542 and @_way@, and the invocation of @make@ will build the ``normal way''.
1543 If @way@ is set, then the other two variables are set in sympathy.
1544 For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@''
1545 and @_way@ is set to ``@_mp@''. These three variables are then used
1546 when constructing file names.
1548 So how does @make@ ever get recursively invoked with @way@ set? There
1549 are two ways in which this happens:
1551 \item For some (but not all) of the standard targets, when in a leaf sub-directory,
1552 @make@ is recursively invoked for each way tag in @$(WAYS)@. You set @WAYS@ to
1553 the list of way tags you want these targets built for. The mechanism here is
1554 very much like the recursive invocation of @make@ in sub-directories
1555 (Section~\ref{sect_subdirs}).
1557 It is up to you to set @WAYS@ in your @Makefile@; this is how you control
1558 what ways will get built.
1559 \item For a useful collection of targets (such as @libHS_mp.a@, @Foo.mp_o@)
1560 there is a rule which recursively invokes @make@ to make the specified
1561 target, setting the @way@ variable. So if you say @gmake Foo.mp_o@
1562 you should see a recursive invocation @gmake Foo.mp_o way=mp@,
1563 and {\em in this recursive invocation the pattern rule for compiling a Haskell
1564 file into a @.o@ file will match}. The key pattern rules (in @suffix.mk@)
1568 $(HC) $(HC_OPTS) $< -o $@
1574 \subsection{When the canned rule isn't right}
1576 Sometimes the canned rule just doesn't do the right thing. For example, in
1577 the @nofib@ suite we want the link step to print out timing information.
1578 The thing to do here is {\em not} to define @HS_PROG@ or @C_PROG@, and instead
1579 define a special purpose rule in your own @Makefile@.
1580 By using different variable names you will avoid the canned rules being included,
1581 and conflicting with yours.
1584 %************************************************************************
1586 \section[booting-from-C]{Booting/porting from C (\tr{.hc}) files}
1587 \index{building GHC from .hc files}
1588 \index{booting GHC from .hc files}
1590 %************************************************************************
1592 This section is for people trying to get GHC going by using the
1593 supplied intermediate C (\tr{.hc}) files. This would probably be
1594 because no binaries have been provided, or because the machine
1595 is not ``fully supported.''
1597 THIS SECTION HASN'T BEEN UPDATED YET. Please let us know if you want to use this
1598 route. Unless someone does, this section may never get written, and the
1599 .hc files distribution may not get built!
1602 %************************************************************************
1604 \section[build-pitfalls]{Known pitfalls in building Glasgow Haskell}
1605 \index{problems, building}
1606 \index{pitfalls, in building}
1607 \index{building pitfalls}
1609 %************************************************************************
1611 WARNINGS about pitfalls and known ``problems'':
1614 %------------------------------------------------------------------------
1616 One difficulty that comes up from time to time is running out of space
1617 in \tr{/tmp}. (It is impossible for the configuration stuff to
1618 compensate for the vagaries of different sysadmin approaches re temp
1621 The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or
1622 even \tr{setenv TMPDIR .} (or the equivalent incantation with the
1623 shell of your choice).
1625 The best way around it is to say
1629 in your @build.mk@ file.
1630 Then GHC and the other @fptools@ programs will use the appropriate directory
1633 %------------------------------------------------------------------------
1635 In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and
1636 even in \tr{ghc/lib}, you may get a few C-compiler warnings. We think
1639 %------------------------------------------------------------------------
1641 When compiling via C, you'll sometimes get ``warning:
1642 assignment from incompatible pointer type'' out of GCC. Harmless.
1644 %------------------------------------------------------------------------
1646 Similarly, \tr{ar}chiving warning messages like the following are not
1649 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1650 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1654 %------------------------------------------------------------------------
1656 Also harmless are some specialisation messages that you may see when
1657 compiling GHC; e.g.:
1659 SPECIALISATION MESSAGES (Desirable):
1661 {-# SPECIALIZE instance Eq [Class] #-}
1662 {-# SPECIALIZE instance Eq (Class, [Class]) #-}
1663 {-# SPECIALIZE instance Outputable [ClassOp] #-}
1664 {-# SPECIALIZE instance Outputable [Id] #-}
1667 %------------------------------------------------------------------------
1669 In compiling the compiler proper (in \tr{compiler/}), you {\em may} get an
1670 ``Out of heap space'' error message. These
1671 can vary with the vagaries of different systems, it seems. The
1672 solution is simple: (1)~add a suitable \tr{-H} flag to the @<module>_HC_OPTS@
1673 @make@ variable in the appropriate @Makefile@;
1674 (2)~try again: \tr{gmake}.
1675 (Section~\ref{sect_suffix}.)
1677 Alternatively, just cut to the chase scene:
1680 % make EXTRA_HC_OPTS=-H32m # or some nice big number
1683 %------------------------------------------------------------------------
1685 Not too long into the build process, you may get a huge complaint
1688 Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27.
1690 This indicates that your \tr{perl} was mis-installed; the binary is
1691 unable to find the files for its ``built-in'' library. Speak to your
1692 perl installer, then re-try.
1694 %------------------------------------------------------------------------
1696 If you try to compile some Haskell, and you get errors from GCC
1697 about lots of things from \tr{/usr/include/math.h}, then your GCC
1698 was mis-installed. \tr{fixincludes} wasn't run when it should've
1701 As \tr{fixincludes} is now automagically run as part of GCC
1702 installation, this bug also suggests that you have an old GCC.
1705 %------------------------------------------------------------------------
1707 You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
1709 % cd $(libdir)/ghc-2.04/sparc-sun-sunos4
1710 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
1712 ? # or, on some machines: ar s $i
1715 We'd be interested to know if this is still necessary.
1717 %------------------------------------------------------------------------
1719 If you end up making documents that involve (La)TeX and/or \tr{tib}
1720 (Simon's favourite), the odds are that something about your/our setup
1721 will reach out and bite you. Yes, please complain; meanwhile,
1722 you can do \tr{make -n whatever.dvi} to see the intended commands,
1723 then try to muddle through, doing them by hand.
1725 %------------------------------------------------------------------------
1727 GHC's sources go through \tr{cpp}
1728 before being compiled, and \tr{cpp} varies a bit from one Unix to another.
1729 One particular gotcha is macro calls like this:
1731 SLIT("Hello, world")
1733 Some \tr{cpp}s treat the comma inside the string as separating two macro arguments,
1736 :731: macro `SLIT' used with too many (2) args
1738 Alas, \tr{cpp} doesn't tell you the offending file!
1740 Workaround: don't put wierd things in string args to \tr{cpp} macros.
1745 % ====================================================================
1746 %Here follow pitfalls that apply to pre-2.02 releases. They should not
1747 %happen any more If they do crop up with 2.02 or later, please let us
1751 %%------------------------------------------------------------------------
1753 %When configuring the support code (mkworld, glafp-utils, etc.), you
1754 %will see mention of \tr{NO_SPECIFIC_PROJECT} and
1755 %\tr{NO_SPECIFIC_VERSION}. This is cool.
1758 %------------------------------------------------------------------------
1760 %Sooner or later in your ``make-worlding'' life you will do and see
1764 % rm -f Makefile.bak; mv Makefile Makefile.bak
1765 %../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=...
1766 %../.././mkworld/jrestoredeps
1767 %==== The new Makefile is for: ====
1768 %make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen
1769 %Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard
1771 %make: Fatal error: Command failed for target `Makefile'
1774 %Don't panic! It should restore your previous \tr{Makefile}, and
1775 %leave the junk one in \tr{Makefile.bad}. Snoop around at your leisure.
1777 % ------------------------------------------------------------------------
1779 %If you do corrupt a \tr{Makefile} totally, or you need to glue a new
1780 %directory into the directory structure (in \tr{newdir}---which must
1781 %have a \tr{Jmakefile}, even if empty), here's a neat trick:
1784 %# move to the directory just above the one where you want a Makefile...
1787 %# make Makefiles, but lie about the directories below...
1788 %make Makefiles SUBDIRS=newdir
1791 %This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and
1792 %it will be properly wired into the general make-world structure.
1794 % ------------------------------------------------------------------------
1796 Don't configure/build/install using a variety of machines. A
1797 mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to
1798 build GHC (\tr{make all}) on a Sun3.
1800 %------------------------------------------------------------------------
1802 %If you build an ``unregisterised'' build, you will get bazillions of
1803 %warnings about `ANSI C forbids braced-groups within expressions'.
1804 %Especially in \tr{ghc/lib}. These are OK.
1809 \begin{onlystandalone}
1812 \end{onlystandalone}