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.
86 Source releases of 2.0x can be compiled up using 2.07 (or subsequent
87 bugfix releases) or the Good Old Compiler, GHC~0.29. Compiling with
88 0.29 is recommended if you're a performance junkie, as 0.29 (still)
89 generates zippier code, but GHC~2.0x is catching up.
91 \item[Build GHC from intermediate C \tr{.hc} files:]
92 You need a working GHC to use a source distribution. What if you don't
93 have a working GHC? Then you have no choice but to ``bootstrap'' up
94 from the intermediate C (\tr{.hc}) files that we provide.
95 Building GHC on an unsupported platform falls into this category.
96 Please see \sectionref{booting-from-C}.
98 Once you have built GHC, you can build the other Glasgow tools with
101 In theory, you can (could?) build GHC with another Haskell compiler
102 (e.g., HBC). We haven't tried to do this for ages and it almost
103 certainly doesn't work any more (for tedious reasons).
105 \item[The CVS repository.]
107 We make source distributions at the same time as binary distributions;
108 i.e. infrequently. They should, however, be pretty thoroughly tested.
109 If you want more up-to-the minute (but less tested) source code then you
110 need to get access to our CVS repository.
112 All the @fptools@ source code is held in a CVS repository. CVS is a
113 pretty good source-code control system, and best of all it works over
116 The repository holds source code only. It holds no mechanically
117 generated files at all. So if you check out a source tree from CVS
118 you will need to install every utility so that you can build all the
119 derived files from scratch.
121 Giving you access to the repository entails some systems administration
122 at our end; and we are a bit nervous about being submerged in bug reports
123 about our current working copy (which is, by definition, in flux). So
124 we are a bit cautious about offering CVS access. Feel free to ask though!
127 If you are going to do any building from sources (either from a source
128 distribution or the CVS repository) then you need to read all of this
131 %************************************************************************
133 \section{Things to check before you start typing}
135 %************************************************************************
137 Here's a list of things to check before you get started.
140 \index{disk space needed}
141 Disk space needed: About 30MB (five hamburgers' worth) of disk space
142 for the most basic binary distribution of GHC; more for some
143 platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
144 Haskell libraries) might take you to 8--10 hamburgers.
146 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
147 build the basic stuff from scratch.
150 All of the above are {\em estimates} of disk-space needs.(I don't yet
151 know the disk requirements for the non-GHC tools).
154 Use an appropriate machine, compilers, and things.
156 SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
157 or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
158 in pretty good shape. \Sectionref{port-info} gives the full run-down
159 on ports or lack thereof.
162 Be sure that the ``pre-supposed'' utilities are installed.
163 Section~\ref{sect_std-utils} elaborates.
166 If you have any problem when building or installing the Glasgow tools,
167 please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If
168 you feel there is still some shortcoming in our procedure or
169 instructions, please report it.
171 For GHC, please see the bug-reporting section of the User's guide
172 (separate document), to maximise the usefulness of your report.
174 If in doubt, please send a message to \tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
178 %************************************************************************
180 \section[port-info]{What machines the Glasgow tools run on}
183 \index{supported platforms}
184 \index{platforms, supported}
186 %************************************************************************
188 The main question is whether or not the Haskell compiler (GHC) runs on
192 architecture/manufacturer/operating-system combination,
193 such as @sparc-sun-solaris2.5.1@. Other common ones are
194 @alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
195 @i386-unknown-solaris2@, @i386-unknown-freebsd@, @i386-unknown-cygwin32@,
196 @m68k-sun-sunos4@, @mips-sgi-irix5@, @sparc-sun-sunos4@,
197 @sparc-sun-solaris2@, @powerpc-ibm-aix@.
199 Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
200 work on all machines for which basic Haskell compiling is supported.
202 Some libraries may only work on a limited number of platforms; for
203 example, a sockets library is of no use unless the operating system
204 supports the underlying BSDisms.
206 %************************************************************************
208 \subsection{What platforms the Haskell compiler (GHC) runs on}
210 %************************************************************************
211 \index{fully-supported platforms}
212 \index{native-code generator}
213 \index{registerised ports}
214 \index{unregisterised ports}
216 The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
217 generator; (b)~next best is a ``registerised''
218 port; (c)~the bare minimum is an ``unregisterised'' port.
219 (``Unregisterised'' is so terrible that we won't say more about it).
221 We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas
222 running OSF/1~V2.0, so those are the ``fully-supported'' platforms,
223 unsurprisingly. Both have native-code generators, for quicker
224 compilations. The native-code generator for iX86 platforms (e.g.,
225 Linux ELF) is {\em nearly} working; but is not turned on by default.
227 Here's everything that's known about GHC ports. We identify platforms
228 by their ``canonical'' CPU/Manufacturer/OS triple.
230 Note that some ports are fussy about which GCC version you use; or
234 %-------------------------------------------------------------------
235 \item[\tr{alpha-dec-osf1}:]
236 \index{alpha-dec-osf1: fully supported}
237 (We have OSF/1 V2.0.) Fully supported, including native-code generator.
238 We recommend GCC 2.6.x or later.
240 %-------------------------------------------------------------------
241 \item[\tr{sparc-sun-sunos4}:]
242 \index{sparc-sun-sunos4: fully supported}
243 Fully supported, including native-code generator.
245 %-------------------------------------------------------------------
246 \item[\tr{sparc-sun-solaris2}:]
247 \index{sparc-sun-solaris2: fully supported}
248 Fully supported, including native-code generator. A couple of quirks,
249 though: (a)~the profiling libraries are bizarrely huge; (b)~the
250 default \tr{xargs} program is atrociously bad for building GHC
251 libraries (see \sectionref{Pre-supposed} for details).
253 %-------------------------------------------------------------------
254 \item[HP-PA box running HP/UX 9.x:]
255 \index{hppa1.1-hp-hpux: registerised port}
256 Works registerised. No native-code generator.
257 For GCC, you're best off with one of the Utah releases of
258 GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}.
259 We think a straight GCC 2.7.x works, too.
261 Concurrent/Parallel Haskell probably don't work (yet).
262 \index{hppa1.1-hp-hpux: concurrent---no}
263 \index{hppa1.1-hp-hpux: parallel---no}
265 %-------------------------------------------------------------------
266 \item[\tr{i386-*-linux} (PCs running Linux---ELF format):]
267 \index{i386-*-linux: registerised port}
268 GHC works registerised.
269 You {\em must} have GCC 2.7.x or later.
270 The iX86 native-code generator is {\em nearly} there, but it
271 isn't turned on by default.
273 Profiling works, and Concurrent Haskell works.
274 \index{i386-*-linux: profiling---yes}
275 \index{i386-*-linux: concurrent---yes}
276 Parallel Haskell probably works.
277 \index{i386-*-linux: parallel---maybe}
279 On old Linux a.out systems: should be the same.
280 \index{i386-*-linuxaout: registerised port}
282 %-------------------------------------------------------------------
283 \item[\tr{i386-*-freebsd} (PCs running FreeBSD 2.2 or higher, and
284 NetBSD/OpenBSD using FreeBSD emulation):] \index{i386-*-freebsd:
285 registerised port} GHC works registerised. Supports same set of
286 bundles as the above.
288 \index{i386-*-freebsd: profiling---yes}
289 \index{i386-*-freebsd: concurrent---yes}
290 \index{i386-*-freebsd: parallel---maybe}
292 %-------------------------------------------------------------------
293 \item[\tr{i386-unknown-cygwin32}:]
294 \index{i386-unknown-cygwin32: fully supported}
295 Fully supported under Win95/NT, including a native
296 code generator. Requires the @cygwin32@ compatibility library and
297 a healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
298 Profiling works, so does Concurrent Haskell.
299 \index{i386-*-cygwin32: profiling---yes}
300 \index{i386-*-cygwin32: concurrent---yes}
302 % ToDo: more documentation on this is reqd here.
304 %-------------------------------------------------------------------
305 \item[\tr{mips-sgi-irix5}:]
306 \index{mips-sgi-irix5: registerised port}
307 GHC works registerised (no native-code generator).
308 I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
309 was built with \tr{--with-gnu-as}; turns out that is important!
311 Concurrent/Parallel Haskell probably don't work (yet).
312 Profiling might work, but it is untested.
313 \index{mips-sgi-irix5: concurrent---no}
314 \index{mips-sgi-irix5: parallel---no}
315 \index{mips-sgi-irix5: profiling---maybe}
317 %-------------------------------------------------------------------
318 \item[\tr{mips-sgi-irix6}:]
319 \index{mips-sgi-irix6: registerised port}
320 Thanks to the fine efforts of Tomasz Cholewo
321 \tr{<tjchol01@mecca.spd.louisville.edu>}, GHC works registerised
322 (no native code generator) under IRIX 6.2 and 6.3. Depends on having
323 specially tweaked version of gcc-2.7.2 around, which can be downloaded
327 http://mecca.spd.louisville.edu/~tjchol01/software/
330 Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
331 \index{mips-sgi-irix6: concurrent---maybe}
332 \index{mips-sgi-irix6: parallel---maybe}
333 \index{mips-sgi-irix6: profiling---yes}
335 %-------------------------------------------------------------------
336 \item[\tr{powerpc-ibm-aix}:]
337 \index{powerpc-ibm-aix: registerised port}
338 GHC works registerised (no native-code generator..yet).
339 I suspect 2.7.x is what you need together with this.
341 Concurrent/Parallel Haskell probably don't work (yet).
342 Profiling might work, but it is untested.
343 \index{mips-sgi-irix5: concurrent---no}
344 \index{mips-sgi-irix5: parallel---no}
345 \index{mips-sgi-irix5: profiling---maybe}
347 %-------------------------------------------------------------------
348 \item[\tr{m68k-apple-macos7} (Mac, using MPW):]
349 \index{m68k-apple-macos7: historically ported}
350 Once upon a time, David Wright in Tasmania has actually
351 gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
352 You may be able to get Thomson's from here. (Not sure that it will
353 excite you to death, but...)
355 No particularly recent GHC is known to work on a Mac.
357 %-------------------------------------------------------------------
358 \item[\tr{m68k-next-nextstep3}:]
359 \index{m68k-next-nextstep3: historically ported}
360 Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29.
361 There's probably a little bit-rot since then, but otherwise it should
364 Concurrent/Parallel Haskell probably won't work (yet).
365 \index{m68k-next-nextstep3: concurrent---no}
366 \index{m68k-next-nextstep3: parallel---no}
368 %-------------------------------------------------------------------
369 \item[\tr{m68k-sun-sunos4} (Sun3):]
370 \index{m68k-sun-sunos4: registerised port}
371 GHC 2.0x hasn't been tried on a Sun3. GHC~0.26 worked registerised.
372 No native-code generator.
374 Concurrent/Parallel Haskell probably don't work (yet).
375 \index{m68k-sun-sunos4: concurrent---no}
376 \index{m68k-sun-sunos4: parallel---no}
379 %************************************************************************
381 \subsection{What machines the other tools run on}
383 %************************************************************************
385 Unless you hear otherwise, the other tools work if GHC works.
387 Haggis requires Concurrent Haskell to work.
388 \index{Haggis, Concurrent Haskell}
391 %************************************************************************
393 \section[installing-bin-distrib]{Installing from binary distributions}
394 \index{binary installations}
395 \index{installation, of binaries}
397 %************************************************************************
399 Installing from binary distributions is easiest, and recommended!
400 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
401 so you've got to ``bootstrap'' it, somehow. We provide
402 machine-generated C-files-from-Haskell for this purpose, but it's
403 really quite a pain to use them. If you must build GHC from its
404 sources, using a binary-distributed GHC to do so is a sensible way to
405 proceed. For the other @fptools@ programs, many are written in Haskell,
406 so binary distributions allow you to install them without having a Haskell compiler.)
409 \subsection{Bundle structure}
411 Binary distributions come in ``bundles,''\index{bundles of binary stuff}
412 one bundle per file called \tr{<bundle>-<platform>.tar.gz}.
413 (See Section~\ref{port-info} for what a platform is.)
414 Suppose that you untar a binary-distribution bundle, thus:
416 % cd /your/scratch/space
417 % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
419 Then you should find a single directory, @fptools@, with the following
422 \item[@Makefile.in@] the raw material from which the @Makefile@ will be made (\sectionref{sect_install}).
423 \item[@configure@] the configuration script (\sectionref{sect_install}).
424 \item[@README@] Contains this file summary.
425 \item[@INSTALL@] Contains this description of how to install the bundle.
426 \item[@ANNOUNCE-<bundle>@] The announcement message for the bundle.
427 \item[@NEWS-<bundle>@] release notes for the bundle -- a longer version of @ANNOUNCE@.
428 \item[@bin/<platform>/@] contains platform-specific executable files to be invoked
429 directly by the user. These are the files that must end up in your path.
430 \item[@lib/<platform>@] contains platform-specific support files for the installation.
431 Typically there is a subdirectory for each @fptools@ project, whose name is
432 the name of the project with its version number. For example, for GHC
433 there would be a sub-directory @ghc-x.xx/@ where @x.xx@ is the version
434 number of GHC in the bundle.
436 These sub-directories have the following general structure:
438 \item[@libHS.a@ etc:] supporting library archives.
439 \item[@ghc-iface.prl@ etc:] support scripts.
440 \item[@import/@] Interface files (@.hi@) for the prelude.
441 \item[@include/@] A few C @#include@ files.
444 \item[@share/@] contains platform-independent support files for the installation.
445 Again, there is a sub-directory for each @fptools@ project.
447 \item[@info/@] contains Emacs info documentation files (one sub-directory per project).
448 \item[@html/@] contains HTML documentation files (one sub-directory per project).
449 \item[@man/@] contains Unix manual pages.
451 This structure is designed so that you can unpack multiple bundles (including
452 ones from different releases or platforms) into a single @fptools@ directory:
454 % cd /your/scratch/space
455 % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
456 % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -
458 When you do multiple unpacks like this, the top level @Makefile@, @README@,
459 and @INSTALL@ get overwritten each time. That's fine -- they should be the same.
460 Likewise, the @ANNOUNCE-<bundle>@ and @NEWS-<bundle>@ files will be duplicated
461 across multiple platforms, so they will be harmlessly overwritten when you do
463 Finally, the @share/@ stuff will get harmlessly overwritten when you do multiple
464 unpacks for one bundle on different platforms.
466 \subsection[sect_install]{Installing}
468 OK, so let's assume that you have unpacked your chosen bundles into
469 a scratch directory @fptools@. What next? Well, you will at least need
470 to run the @configure@ script by changing your directory to @fptools@.
471 That should convert @Makefile.in@ to @Makefile@.
473 You can now either start using the tools {\em in-situ} without going
474 through any installation process, just type @make in-place@ to set the
475 tools up for this (you have to be in the @fptools@ directory for
476 this). You'll also want to add the path which @make@ will now echo to
477 your @PATH@ environment variable. This option is useful if you simply want
478 to try out the package and/or you don't have the necessary priviledges (or
479 inclination) to properly install the tools locally. Note that if you
480 do decide to install the package `properly' at a later date, you have
481 to go through the installation steps that follows.
483 To install an @fptools@ package, you'll have to do the following:
486 \item Edit the @Makefile@ and check the settings of the following variables:
488 \item[@platform@] the platform you are going to install for.
489 \item[@bindir@] the directory in which to install user-invokable binaries.
490 \item[@libdir@] the directory in which to install platform-dependent support files.
491 \item[@datadir@] the directory in which to install platform-independent support files.
492 \item[@infodir@] the directory in which to install Emacs info files.
493 \item[@htmldir@] the directory in which to install HTML documentation.
494 \item[@dvidir@] the directory in which to install DVI documentation.
496 The values for these variables can be set through invocation of the
497 @configure@ script that comes with the distribution, but doing an optical
498 diff to see if the values match your expectations is always a Good Idea.
500 {\em Instead of running @configure@, it is perfectly OK to copy
501 @Makefile.in@ to @Makefile@ and set all these variables directly
502 yourself. But do it right!}
504 \item Run @make install@. This {\em should} work with ordinary Unix
505 @make@ -- no need for fancy stuff like GNU @make@.
507 \item \tr{rehash} (t?csh users), so your shell will see the new stuff
508 in your bin directory.
511 Once done, test your ``installation'' as suggested in
512 \sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you
513 can see exactly what pathnames it's using.
515 If things don't work as expected, check the list of know pitfalls
516 \sectionref{build-pitfalls}.
519 When installing the user-invokable binaries, this installation
520 procedure will install GHC as @ghc-x.xx@ where @x.xx@ is the version
521 number of GHC. It will also make a link (in the binary installation
522 directory) from @ghc@ to @ghc-x.xx@. If you install multiple versions
523 of GHC then the last one ``wins'', and ``@ghc@'' will invoke the last
524 one installed. You can change this manually if you want. But
525 regardless, @ghc-x.xx@ should always invoke GHC version @x.xx@.
527 \subsection{What bundles there are}
529 There are plenty of ``non-basic'' GHC bundles. The files for them are
530 called \tr{ghc-x.xx-<bundle>-<platform>.tar.gz}, where the
531 \tr{<platform>} is as above, and \tr{<bundle>} is one of these:
533 \item[\tr{prof}:] Profiling with cost-centres. You probably want this.
535 \item[\tr{conc}:] Concurrent Haskell features. You may want this.
537 \item[\tr{par}:] Parallel Haskell features (sits on top of PVM).
538 You'll want this if you're into that kind of thing.
540 \item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator
541 (hmm... mainly for implementors).
543 \item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed
544 information about ``what happened when I ran this program''---really
547 \item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell.
549 \item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell.
552 One likely scenario is that you will grab {\em three} binary
553 bundles---basic, profiling, and concurrent.
557 %************************************************************************
559 \subsection[GHC_test]{Test that GHC seems to be working}
560 \index{testing a new GHC}
562 %************************************************************************
564 The way to do this is, of course, to compile and run {\em this} program
565 (in a file \tr{Main.hs}):
567 main = putStr "Hello, world!\n"
570 First, give yourself a convenient way to execute the driver script
571 \tr{ghc/driver/ghc}, perhaps something like...
573 % ln -s /local/src/ghc-x.xx/ghc/driver/ghc ~/bin/alpha/ghc
577 Compile the program, using the \tr{-v} (verbose) flag to verify that
578 libraries, etc., are being found properly:
580 % ghc -v -o hello Main.hs
589 Some simple-but-profitable tests are to compile and run the
590 notorious \tr{nfib} program, using different numeric types. Start
591 with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float},
592 \tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code
593 for this is distributed in \tr{ghc/misc/examples/nfib/}.
595 For more information on how to ``drive'' GHC,
596 either do \tr{ghc -help} or consult the User's Guide (distributed in
597 \tr{ghc/docs/users_guide}).
600 %************************************************************************
602 \section[Pre-supposed]{Installing pre-supposed utilities}
603 \index{pre-supposed utilities}
604 \index{utilities, pre-supposed}
606 %************************************************************************
608 \label{sect_std-utils}
610 Here are the gory details about some utility programs you may need;
611 \tr{perl} and \tr{gcc} are the only important ones. (PVM is important
612 if you're going for Parallel Haskell.) The \tr{configure} script will
613 tell you if you are missing something.
617 \index{pre-supposed: Perl}
618 \index{Perl, pre-supposed}
619 {\em You have to have Perl to proceed!} Perl is a language quite good
620 for doing shell-scripty tasks that involve lots of text processing.
621 It is pretty easy to install.
623 Perl~5 is the current version; GHC should be Perl~4 friendly though.
624 For Win32 platforms, Perl~5 is recommended, we even strongly suggest
625 you pick up a port of Perl~5 for \tr{cygwin32}, as the common
626 Hip/ActiveWare port of Perl is not Cool Enough for our purposes.
628 Perl should be put somewhere so that it can be invoked by the \tr{#!}
629 script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred;
630 we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should
631 be less than 32 characters long.
633 \item[GNU C (\tr{gcc}):]
634 \index{pre-supposed: GCC (GNU C compiler)}
635 \index{GCC (GNU C compiler), pre-supposed}
636 The current version is 2.7.2.
638 If your GCC dies with ``internal error'' on some GHC source file,
639 please let us know, so we can report it and get things improved.
640 (Exception: on \tr{iX86} boxes---you may need to fiddle with GHC's
641 \tr{-monly-N-regs} option; ask if confused...)
643 \item[PVM version 3:]
644 \index{pre-supposed: PVM3 (Parallel Virtual Machine)}
645 \index{PVM3 (Parallel Virtual Machine), pre-supposed}
646 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
647 run. (You only need this if you plan to run Parallel Haskell.
648 Concurent Haskell, which runs concurrent threads on a uniprocessor
650 Underneath PVM, you can have (for example) a network of
651 workstations (slow) or a multiprocessor box (faster).
653 The current version of PVM is 3.3.11; we use 3.3.7. It is readily
654 available on the net; I think I got it from \tr{research.att.com}, in
657 A PVM installation is slightly quirky, but easy to do. Just follow
658 the \tr{Readme} instructions.
660 \item[\tr{xargs} on Solaris2:]
661 \index{xargs, presupposed (Solaris only)}
662 \index{Solaris: alternative xargs}
663 The GHC libraries are put together with something like:
665 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
667 Unfortunately the Solaris \tr{xargs} (the shell-script equivalent
668 of \tr{map}) only ``bites off'' the \tr{.o} files a few at a
669 time---with near-infinite rebuilding of the symbol table in
672 The best solution is to install a sane \tr{xargs} from the GNU
673 findutils distribution. You can unpack, build, and install the GNU
674 version in the time the Solaris \tr{xargs} mangles just one GHC
677 \item[\tr{bash} (Parallel Haskell only):]
678 \index{bash, presupposed (Parallel Haskell only)}
679 Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles''
680 to PostScript, is written in Bash (GNU's Bourne Again shell).
681 This bug will be fixed (someday).
684 \index{pre-supposed: makeindex}
685 \index{makeindex, pre-supposed}
686 You won't need this unless you are re-making our documents. Makeindex
687 normally comes with a \TeX{} distribution, but if not, we can provide
688 the latest and greatest.
691 \index{pre-supposed: tgrind}
692 \index{tgrind, pre-supposed}
693 This is required only if you remake lots of our documents {\em and}
694 you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate
695 programming), to do ``fancy'' typesetting of your code. {\em
699 \index{pre-supposed: flex}
700 \index{flex, pre-supposed}
701 This is a quite-a-bit-better-than-Lex lexer. Used in the
702 literate-programming stuff. You won't need it unless you're hacking
703 on some of our more obscure stuff.
704 On our machines, the version in @/bin@ doesn't work; you need the
705 GNU version. Find out by saying @flex --version@ (our current version
706 is 2.5.3, but maybe earlier ones will work). If it doesn't know about
707 the @--version@ flag, it ain't the right @flex@.
710 \index{pre-supposed: non-worthless Yacc}
711 \index{Yacc, pre-supposed}
712 If you mess with the Haskell parser, you'll need a Yacc that can cope.
713 The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK;
714 Berkeley yacc, \tr{byacc}, is not OK.
717 \index{pre-supposed: sed}
718 \index{sed, pre-supposed}
719 You need a working @sed@ if you are going to build from sources.
720 The build-configuration stuff needs it.
721 GNU sed version 2.0.4 is no good! It has a bug in it that is tickled
722 by the build-configuration. 2.0.5 is ok. Others are probably ok too
723 (assuming we don't create too elaborate configure scripts..)
726 Two @fptools@ projects are worth a quick note at this point, because
727 they are useful for all the others:
729 \item @glafp-utils@ contains several utilities which aren't
730 particularly Glasgow-ish, but Occasionally Indispensable. Like
731 @lndir@ for creating symbolic link trees.
733 \item @literate@ contains the Glasgow-built tools for generating
734 documentation. (The unoriginal idea is to be able to generate @latex@, @info@,
735 and program code from a single source file.) To get anywhere you'll
736 need at least @lit2pgm@, either from the @literate@ project, or
737 because it's already installed on your system.
742 %************************************************************************
744 \section[building-from-source]{Building from source}
745 \index{Building from source}
747 %************************************************************************
749 You've been rash enough to want to build some of
750 the Glasgow Functional Programming tools (GHC, Happy,
751 nofib, etc) from source. You've slurped the source,
752 from the CVS repository or from a source distribution, and
753 now you're sitting looking at a huge mound of bits, wondering
756 Gingerly, you type @make all@. Wrong already!
758 This rest of this guide is intended for duffers like me, who aren't really
759 interested in Makefiles and systems configurations, but who need
760 a mental model of the interlocking pieces so that they can
761 make them work, extend them consistently when adding new
762 software, and lay hands on them gently when they don't work.
764 \subsection{Your source tree}
767 The source code is held in your {\em source tree}.
768 The root directory of your source tree {\em must}
769 contain the following directories and files:
771 \item @Makefile@: the root Makefile.
772 \item @mk/@: the directory that contains the
773 main Makefile code, shared by all the
775 \item @configure.in@, @config.sub@, @config.guess@:
776 these files support the configuration process.
779 All the other directories are individual {\em projects} of the
780 @fptools@ system --- for example, the Glasgow Haskell Compiler (@ghc@),
781 the Happy parser generator (@happy@), the @nofib@ benchmark suite,
783 You can have zero or more of these. Needless to say, some of them
784 are needed to build others. For example, you need @happy@ to build
785 @ghc@. You can either grab @happy@ too, or else you can use
786 a version of @happy@ that's already installed on your system, or
787 grab a binary distribution of @happy@ and install it.
789 The important thing to remember is that even if you want only one
790 project (@happy@, say), you must have a source tree whose root
791 directory contains @Makefile@, @mk/@, @configure.in@, and the
792 project(s) you want (@happy/@ in this case). You cannot get by with
793 just the @happy/@ directory.
795 \subsection{Build trees}
797 While you can build a system in the source tree, we don't recommend it.
798 We often want to build multiple versions of our software
799 for different architectures, or with different options (e.g. profiling).
800 It's very desirable to share a single copy of the source code among
803 So for every source tree we have zero or more {\em build trees}. Each
804 build tree is initially an exact copy of the source tree, except that
805 each file is a symbolic link to the source file, rather than being a
806 copy of the source file. There are ``standard'' Unix utilities that
807 make such copies, so standard that they go by different names:
808 @lndir@, @mkshadowdir@ are two (If you don't have either, the source
809 distribution includes sources for the \tr{X11} \tr{lndir} --- check
810 out \tr{fptools/glafp-utils/lndir} ).
812 The build tree does not need to be anywhere near the source tree in
813 the file system. Indeed, one advantage of separating the build tree
814 from the source is that the build tree can be placed in a
815 non-backed-up partition, saving your systems support people from
816 backing up untold megabytes of easily-regenerated, and
817 rapidly-changing, gubbins. The golden rule is that (with a single
818 exception -- Section~\ref{sect_build-config}) {\em absolutely
819 everything in the build tree is either a symbolic link to the source
820 tree, or else is mechanically generated}. It should be perfectly OK
821 for your build tree to vanish overnight; an hour or two compiling and
822 you're on the road again.
824 You need to be a bit careful, though, that any new files you create
825 (if you do any development work) are in the source tree, not a build tree!
827 Remember, that the source files in the build tree are {\em symbolic
828 links} to the files in the source tree. (The build tree soon
829 accumulates lots of built files like @Foo.o@, as well.) You can {\em
830 delete} a source file from the build tree without affecting the source
831 tree (though it's an odd thing to do). On the other hand, if you {\em
832 edit} a source file from the build tree, you'll edit the source-tree
833 file directly. (You can set up Emacs so that if you edit a source
834 file from the build tree, Emacs will silently create an edited copy of
835 the source file in the build tree, leaving the source file unchanged;
836 but the danger is that you think you've edited the source file whereas
837 actually all you've done is edit the build-tree copy. More commonly
838 you do want to edit the source file.)
840 Like the source tree, the top level of your build tree must (a linked
841 copy of) the root directory of the @fptools@ suite. Inside Makefiles,
842 the root of your build tree is called @$(FPTOOLS_TOP)@. In the rest
843 of this document path names are relative to @$(FPTOOLS_TOP)@ unless
844 otherwise stated. For example, the file @ghc/mk/target.mk@ is
845 actually @$(FPTOOLS_TOP)/ghc/mk/target.mk@.
848 \subsection{Getting the build you want}
849 \label{sect_build-config}
851 When you build @fptools@ you will be compiling code on a particular
852 {\em host platform}, to run on a particular {\em target platform}
853 (usually the same as the host platform)\index{platform}. The
854 difficulty is that there are minor differences between different
855 platforms; minor, but enough that the code needs to be a bit different
856 for each. There are some big differences too: for a different
857 architecture we need to build GHC with a different native-code
860 There are also knobs you can turn to control how the @fptools@
861 software is built. For example, you might want to build GHC optimised
862 (so that it runs fast) or unoptimised (so that you can compile it fast
863 after you've modified it. Or, you might want to compile it with
864 debugging on (so that extra consistency-checking code gets included)
867 All of this stuff is called the {\em configuration} of your build.
868 You set the configuration using an exciting three-step process.
871 \item[Step 1: get ready for configuration.] Change directory to
872 @$(FPTOOLS)@ and issue the command @autoconf@ (with no
873 arguments). This GNU program converts @$(FPTOOLS)/configure.in@ to a
874 shell script called @$(FPTOOLS)/configure@.
876 Both these steps are completely platform-independent; they just mean
877 that the human-written file (@configure.in@) can be short, although
878 the resulting shell script, @configure@, and @mk/config.h.in@, are
881 In case you don't have @autoconf@ we distribute the results,
882 @configure@, and @mk/config.h.in@, with the source distribution. They
883 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.
910 @configure@ caches the results of its run in @config.cache@.
911 Quite often you don't want that; you're running @configure@ a second time
912 because something has changed. In that case, simply delete @config.cache@.
914 \item[Step 3: build configuration.] Next, you say how this build
915 of @fptools@ is to differ from the standard defaults by creating a new
917 {\em in the build tree}. This file is the one and only
918 file you edit in the build tree, precisely because it says how
919 this build differs from the source. (Just in case your build tree
920 does die, you might want to keep a private directory of @build.mk@ files,
921 and use a symbolic link in each build tree to point to the appropriate one.)
922 So @mk/build.mk@ never
923 exists in the source tree --- you create one in each build tree
924 from the template. We'll discuss what to put in it shortly.
926 And that's it for configuration. Simple, eh?
928 What do you put in your build-specific configuration
929 file @mk/build.mk@? {\em For almost all purposes all you will do is
930 put make variable definitions that override those in @mk/config.mk.in@}.
931 The whole point of @mk/config.mk.in@ --- and its derived
932 counterpart @mk/config.mk@ --- is to define the build configuration. It is heavily
933 commented, as you will see if you look at it.
934 So generally, what you do is edit @mk/config.mk.in@ (read-only), and add definitions
935 in @mk/build.mk@ that override any of the @config.mk@ definitions that you
936 want to change. (The override occurs because the main boilerplate file,
937 @mk/boilerplate.mk@, includes @build.mk@ after @config.mk@.)
939 For example, @config.mk.in@ contains the definition:
941 ProjectsToBuild = glafp-utils literate happy ghc hslibs
943 The accompanying comment explains that this is the list of enabled
944 projects; that is, if (after configuring) you type @gmake all@
945 in @FPTOOLS_TOP@ three specified projects will be made.
946 If you want to add @green-card@, you can add this line to @build.mk@:
948 ProjectsToBuild += green-card
952 ProjectsToBuild = glafp-utils literate happy ghc hslibs green-card
954 (GNU @make@ allows existing definitions to have new text appended using
955 the ``@+=@'' operator, which is quite a convenient feature.)
957 When reading @config.mk.in@, remember that anything between ``{\tt @@...@@}'' signs
958 is going to be substituted by @configure@ later. You {\em can} override
959 the resulting definition if you want,
960 but you need to be a bit surer what you are doing.
961 For example, there's a line that says:
965 This defines the Make variables @YACC@ to the pathname for a Yacc that
966 @configure@ finds somewhere. If you have your own pet Yacc you want
967 to use instead, that's fine. Just add this line to @mk/build.mk@:
971 You do not {\em have} to have a @mk/build.mk@ file at all; if you don't,
972 you'll get all the default settings from @mk/config.mk.in@.
974 You can also use @build.mk@ to override anything that @configure@ got
975 wrong. One place where this happens often is with the definition of
976 @FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path
977 to the top of your source tree, but if your system uses an automounter
978 then the correct directory is hard to find automatically. If you find
979 that @configure@ has got it wrong, just put the correct definition in
982 \subsection{The story so far}
984 Let's summarise the steps you need to carry to get yourself
985 a fully-configured build tree from scratch.
988 \item Get your source tree from somewhere (CVS repository or
989 source distribution). Say you call the root directory
990 @myfptools@ (it does not have to be called @fptools@).
991 Make sure that you have the essential files (see Section~\ref{source-tree}).
993 \item Use @lndir@ or @mkshadowdir@ to create a build tree.
996 mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
998 You probably want to give the build tree a name that
999 suggests its main defining characteristic (in your mind at least),
1000 in case you later add others.
1002 \item Change directory to the build tree. Everything is going
1003 to happen there now.
1005 cd /scratch/joe-bloggs/myfptools-sun4
1007 \item Prepare for system configuration:
1011 (You can skip this step if you are starting from a source distribution,
1012 and you already have @configure@ and @mk/config.h.in@.)
1014 \item Do system configuration:
1019 \item Create the file @mk/build.mk@,
1020 adding definitions for your desired configuration options.
1025 You can make subsequent changes to @mk/build.mk@ as often
1026 as you like. You do not have to run any further configuration
1027 programs to make these changes take effect.
1028 In theory you should, however, say @gmake clean@, @gmake all@,
1029 because configuration option changes could affect anything --- but in practice you are likely to know what's affected.
1031 \subsection{Making things}
1033 At this point you have made yourself a fully-configured build tree,
1034 so you are ready to start building real things.
1036 The first thing you need to know is that
1037 {\em you must use GNU @make@, usually called @gmake@, not standard Unix @make@}.
1038 If you use standard Unix @make@ you will get all sorts of error messages
1039 (but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities
1042 \subsection[sect_standard-targets]{Standard targets}
1044 In any directory you should be able to make the following:
1046 \item[@boot@:] does the one-off preparation required to get ready
1047 for the real work. Notably, it does @gmake depend@ in all directories
1048 that contain programs. But @boot@ does more. For example, you can't
1049 do @gmake depend@ in a directory of C program until you have converted
1050 the literate @.lh@ header files into standard @.h@ header files.
1051 Similarly, you convert a literate file to illiterate form until you
1052 have built the @literate@ tools. @boot@ takes care of these
1053 inter-directory dependencies.
1055 You should say @gmake boot@ right after configuring your build tree,
1056 but note that this is a one-off, i.e., there's no need to re-do
1057 @gmake boot@ if you should re-configure your build tree at a later
1058 stage (no harm caused if you do though).
1060 \item[@all@:] makes all the final target(s) for this Makefile.
1061 Depending on which directory you are in a ``final target''
1062 may be an executable program, a library archive, a shell script,
1063 or a Postscript file.
1064 Typing @gmake@ alone is generally the same as typing @gmake all@.
1066 \item[@install@:] installs the things built by @all@. Where does it
1067 install them? That is specified by @mk/config.mk.in@; you can
1068 override it in @mk/build.mk@.
1070 \item[@uninstall@:] reverses the effect of @install@.
1072 \item[@clean@:] remove all easily-rebuilt files.
1074 \item[@veryclean@:] remove all files that can be rebuilt at all.
1075 There's a danger here that you may remove a file that needs a more
1077 utility to rebuild it (especially if you started from a source
1080 \item[@check@:] run the test suite.
1082 All of these standard targets
1083 automatically recurse into sub-directories.
1084 Certain other standard targets do not:
1086 \item[@configure@:] is only available in the root directory @$(FPTOOLS)@;
1087 it has been discussed in Section~\ref{sect_build-config}.
1089 \item[@depend@:] make a @.depend@ file in each directory that needs
1090 it. This @.depend@ file contains mechanically-generated dependency
1091 information; for example, suppose a directory contains a Haskell
1092 source module @Foo.lhs@ which imports another module @Baz@.
1093 Then the generated @.depend@ file will contain the dependency:
1097 which says that the object file @Foo.o@ depends on the interface
1098 file @Baz.hi@ generated by compiling module @Baz@.
1099 The @.depend@ file is automatically included by every Makefile.
1101 \item[@binary-dist@:] make a binary distribution.
1103 \item[@dist@:] make a source distribution.
1106 \subsection{Other targets}
1108 Most @Makefiles@ have targets other than these. You can find
1109 this out by looking in the @Makefile@ itself.
1114 %************************************************************************
1116 \section{The @Makefile@ architecture}
1118 %************************************************************************
1121 @make@ is great if everything works --- you type @gmake install@ and, lo,
1122 the right things get compiled and installed in the right places.
1123 Our goal is to make this happen often, but somehow it often doesn't;
1125 some wierd error message eventually emerges from the bowels of a directory
1126 you didn't know existed.
1128 The purpose of this section is to give you a road-map to help you figure
1129 out what is going right and what is going wrong.
1131 \subsection{A small project}
1133 To get started, let us look at the @Makefile@ for an imaginary small
1134 @fptools@ project, @small@. Each project in @fptools@ has its own
1135 directory in @FPTOOLS_TOP@, so the @small@ project will have its own
1136 directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there
1137 will be a @Makefile@, looking something like this:
1139 # Makefile for fptools project "small"
1142 include $(TOP)/mk/boilerplate.mk
1144 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1147 include $(TOP)/target.mk
1149 This @Makefile@ has three sections:
1151 \item The first section includes\footnote{One of the
1152 most important features of GNU @make@ that we use is the ability
1153 for a @Makefile@ to include another named file, very like @cpp@'s @#include@ directive.}
1154 a file of ``boilerplate'' code from the
1155 level above (which in this case will be @FPTOOLS_TOP/mk/boilerplate.mk@).
1156 As its name suggests, @boilerplate.mk@ consists of a large quantity of standard
1157 @Makefile@ code. We discuss this boilerplate in more detail in Section~\ref{sect_boiler}.
1159 Before the @include@ statement, you must define the @make@ variable
1160 @TOP@ to be the directory containing the @mk@ directory in which
1161 the @boilerplate.mk@ file is.
1162 It is {\em not} OK to simply say
1164 include ../mk/boilerplate.mk # NO NO NO
1166 Why? Because the @boilerplate.mk@ file needs to know where it is,
1167 so that it can, in turn, @include@ other files.
1168 (Unfortunately, when an @include@d file does an
1169 @include@, the filename is treated
1170 relative to the directory in which @gmake@ is being run, not
1171 the directory in which the @included@ sits.)
1173 {\em every file @foo.mk@
1174 assumes that @$(TOP)/mk/foo.mk@ refers to itself.}
1175 It is up to the @Makefile@ doing the @include@ to ensure this
1178 Files intended for inclusion in other @Makefile@s are written to have
1179 the following property:
1180 {\em after @foo.mk@ is @include@d, it leaves @TOP@ containing the same
1181 value as it had just before the @include@ statement}.
1182 In our example, this invariant guarantees that the @include@
1183 for @target.mk@ will look in the same directory as that for
1186 \item The second section
1187 defines the following standard @make@ variables: @SRCS@ (the source files from
1188 which is to be built), and @HS_PROG@ (the
1189 executable binary to be built).
1190 We will discuss in more detail what the ``standard variables'' are,
1191 and how they affect what happens, in Section~\ref{sect_targets}.
1193 The definition for @SRCS@ uses the useful GNU @make@
1194 construct @$(wildcard@~$pat$@)@, which expands to a list of all the
1195 files matching the pattern $pat$ in the current directory.
1196 In this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@ files
1197 in the directory. (Let's suppose there is one of each, @Foo.lhs@
1200 \item The last section includes a second file of standard code,
1201 called @target.mk@. It contains the rules that tell @gmake@
1202 how to make the standard targets
1203 (Section~\ref{sect_standard-targets}).
1204 Why, you ask, can't this standard code
1205 be part of @boilerplate.mk@? Good question.
1206 We discuss the reason later, in Section~\ref{sect_boiler-arch}.
1208 You do not {\em have} to @include@ the @target.mk@ file. Instead,
1209 you can write rules of your own for all the standard targets.
1210 Usually, though, you will find quite a big payoff from using
1212 @target.mk@; the price tag is that you have to understand
1213 what canned rules get enabled, and what they do (Section~\ref{sect_targets}).
1216 In our example @Makefile@, most of the work is done
1217 by the two @include@d files. When you say @gmake all@,
1218 the following things happen:
1220 \item @gmake@ figures out that the object files are @Foo.o@ and @Baz.o@.
1221 \item It uses a boilerplate pattern rule to compile
1222 @Foo.lhs@ to @Foo.o@ using
1223 a Haskell compiler. (Which one? That is set in the build configuration.)
1224 \item It uses another standard pattern rule to compile @Baz.c@ to @Baz.o@,
1225 using a C compiler. (Ditto.)
1226 \item It links the resulting @.o@ files together to make @small@,
1227 using the Haskell compiler to do the link step. (Why not use @ld@? Because
1228 the Haskell compiler knows what standard librarise to link in. How did @gmake@
1229 know to use the Haskell compiler to do the link, rather than the C compiler?
1230 Because we set the variable @HS_PROG@ rather than @C_PROG@.)
1232 All @Makefile@s should follow the above three-section format.
1234 \subsection{A larger project}
1236 Larger projects are usually structured into a nummber of sub-directories,
1237 each of which has its own @Makefile@. (In very large projects, this
1238 sub-structure might be iterated recursively, though that is rare.)
1239 To give you the idea, here's part of the directory structure for
1240 the (rather large) @ghc@ project:
1251 ...source files for documentation...
1255 ...source files for driver...
1259 parser/...source files for parser...
1260 renamer/...source files for renamer...
1263 The sub-directories @docs@, @driver@, @compiler@, and so on, each contains
1264 a sub-component of @ghc@, and each has its own @Makefile@.
1265 There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@.
1266 It does most of its work by recursively invoking @gmake@
1267 on the @Makefile@s in the sub-directories.
1268 We say that @ghc/Makefile@ is a {\em non-leaf @Makefile@},
1269 because it does little except organise its children, while the @Makefile@s
1270 in the sub-directories are all {\em leaf @Makefile@s}. (In principle
1271 the sub-directories might themselves contain a non-leaf @Makefile@ and
1272 several sub-sub-directories, but that does not happen in @ghc@.)
1274 The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even
1275 though the @ghc/compiler@ has sub-directories, because these sub-directories
1276 do not themselves have @Makefile@ in them. They are just used to structure
1277 the collection of modules that make up @ghc@, but all are managed by the
1278 single @Makefile@ in @ghc/compiler@.
1280 You will notice that @ghc/@ also contains a directory @ghc/mk/@.
1281 It contains @ghc@-specific @Makefile@ boilerplate code.
1284 \item @ghc/mk/boilerplate.mk@ is included at the top of @ghc/Makefile@,
1285 and of all the leaf @Makefile@s in the sub-directories.
1286 It in turn @include@s the main boilerplate file @mk/boilerplate.mk@.
1288 \item @ghc/mk/target.mk@ is @include@d at the bottom of @ghc/Makefile@,
1289 and of all the leaf @Makefiles@ in the sub-directories.
1290 It in turn @include@s the file @mk/target.mk@.
1292 So these two files are the place to look for @ghc@-wide customisation
1293 of the standard boilerplate.
1297 \subsection{Boilerplate architecture}
1298 \label{sect_boiler-arch}
1300 Every @Makefile@ includes a @boilerplate.mk@ file at the top,
1301 and @target.mk@ file at the bottom. In this section we discuss
1302 what is in these files, and why there have to be two of them.
1305 \item @boilerplate.mk@ consists of:
1307 \item {\em Definitions of millions of @make@ variables} that collectively
1308 specify the build configuration. Examples: @HC_OPTS@, the options to
1309 feed to the Haskell compiler; @NoFibSubDirs@, the sub-directories to
1310 enable within the @nofib@ project; @GhcWithHc@, the name of the
1311 Haskell compiler to use when compiling @GHC@ in the @ghc@ project.
1312 \item {\em Standard pattern rules} that tell @gmake@ how to construct
1313 one file from another.
1315 @boilerplate.mk@ needs to be @include@d at the {\em top} of each
1316 @Makefile@, so that the
1317 user can replace the boilerplate definitions or pattern rules by simply
1318 giving a new definition or pattern rule in the @Makefile@. @gmake@ simply
1319 takes the last definition as the definitive one.
1321 Instead of {\em replacing} boilerplate definitions, it is also quite
1322 common to {\em augment} them. For example, a @Makefile@ might say:
1326 thereby adding ``@-O@'' to the end of @SRC_HC_OPTS@.
1328 \item @target.mk@ contains @make@ rules for the standard targets described
1329 in Section~\ref{sect_standard-targets}.
1330 These rules are selectively included, depending on the setting of
1331 certain @make@ variables. These variables are usually set in the middle
1332 section of the @Makefile@ between the two @include@s.
1334 @target.mk@ must be included at the end (rather than being part of @boilerplate.mk@)
1335 for several tiresome reasons:
1337 \item @gmake@ commits target and dependency lists earlier than it should.
1338 For example, @target.mk@ has a rule that looks like this:
1340 $(HS_PROG) : $(OBJS)
1341 $(HC) $(LD_OPTS) $< -o $@
1343 If this rule was in @boilerplate.mk@ then @$(HS_PROG)@ and @$(OBJS)@
1344 would not have their final values at the moment @gmake@ encountered the
1345 rule. Alas, @gmake@ takes a snapshot of their current values, and
1346 wires that snapshot into the rule.
1347 (In contrast, the commands executed when the rule ``fires'' are
1348 only substituted at the moment of firing.)
1349 So, the rule must follow the definitions given in the @Makefile@ itself.
1351 \item Unlike pattern rules, ordinary rules cannot be overriden or
1352 replaced by subsequent rules for the same target (at least not without an
1353 error message). Including ordinary rules in @boilerplate.mk@ would
1354 prevent the user from writing rules for specific targets in specific cases.
1356 \item There are a couple of other reasons I've forgotten, but it doesn't
1361 \subsection{The main @mk/boilerplate.mk@ file}
1364 If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find that
1365 it consists of the following sections, each held in a separate file:
1367 \item[@config.mk@] is the build configuration file we discussed at length
1368 in Section~\ref{sect_build-config}.
1370 \item[@paths.mk@] defines @make@ variables for pathnames and file
1371 lists. In particular, it gives definitions for:
1373 \item[@SRCS@:] all source files in the current directory.
1374 \item[@HS_SRCS@:] all Haskell source files in the current directory.
1375 It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value
1376 @HS_SRCS@ will follow suit.
1377 \item[@C_SRCS@:] similarly for C source files.
1378 \item[@HS_OBJS@:] the @.o@ files derived from @$(HS_SRCS)@.
1379 \item[@C_OBJS@:] similarly for @$(C_SRCS)@.
1380 \item[@OBJS@:] the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@.
1382 Any or all of these definitions can easily be overriden by giving new
1383 definitions in your @Makefile@. For example,
1384 if there are things in the current directory that look like source files
1385 but aren't, then you'll need to set @SRCS@ manually in your @Makefile@.
1386 The other definitions will then work from this new definition.
1388 What, exactly, does @paths.mk@ consider a ``source file'' to be.
1389 It's based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc),
1390 but this is the kind of detail that changes
1391 more rapidly, so rather than enumerate the source suffices here the best thing
1392 to do is to look in @paths.mk@.
1394 \item[@opts.mk@] defines @make@ variables for option strings to
1395 pass to each program. For example, it defines @HC_OPTS@, the
1396 option strings to pass to the Haskell compiler. See \sectionref{sect_suffix}.
1398 \item[@suffix.mk@] defines standard pattern rules -- see \sectionref{sect_suffix}
1400 Any of the variables and pattern rules defined by the boilerplate file
1401 can easily be overridden in any particular @Makefile@, because
1402 the boilerplace @include@ comes first. Definitions after this
1403 @include@ directive simply override the default ones in @boilerplate.mk@.
1405 \subsection[sect_suffix]{Pattern rules and options}
1407 The file @suffix.mk@ defines standard {\em pattern rules} that say how to build one kind
1408 of file from another, for example, how to build a @.o@ file from a @.c@ file.
1409 (GNU @make@'s {\em pattern rules} are more powerful and easier to use than
1410 Unix @make@'s {\em suffix rules}.)
1412 Almost all the rules look something like this:
1416 $(CC) $(CC_OPTS) -c $< -o $@
1418 Here's how to understand the rule. It says that $something@.o@$ (say @Foo.o@)
1419 can be built from $something@.c@$ (@Foo.c@), by invoking the C compiler
1420 (path name held in @$(CC)@), passing to it the options @$(CC_OPTS)@ and the rule's
1422 file of the rule @$<@ (@Foo.c@ in this case), and putting the result in
1423 the rule's target @$@@@ (@Foo.o@ in this case).
1425 Every program is held in a @make@ variable defined in @mk/config.mk@ --- look in @mk/config.mk@ for
1426 the complete list. One important one is the Haskell compiler, which is called @$(HC)@.
1428 Every programs options are are held in a @make@ variables called @<prog>_OPTS@.
1429 the @<prog>_OPTS@ variables are defined in @mk/opts.mk@. Almost all of them are defined
1432 CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
1434 The four variables from which @CC_OPTS@ is built have the following meaning:
1436 \item[@SRC_CC_OPTS@:] options passed to all C compilations.
1437 \item[@WAY_<way>_CC_OPTS@:] options passed to C compilations for way @<way>@. For example,
1438 @WAY_mp_CC_OPTS@ gives options to pass to the C compiler when compiling way @mp@.
1439 The variable @WAY_CC_OPTS@ holds options to pass to the C compiler when compiling the standard way.
1440 (Section~\ref{sect_ways} dicusses multi-way compilation.)
1441 \item[@<module>_CC_OPTS@:] options to pass to the C compiler that are specific to module @<module>@.
1442 For example, @SMap_CC_OPTS@ gives the specific options to pass to the C compiler when compiling
1444 \item[@EXTRA_CC_OPTS@:] extra options to pass to all C compilations. This is intended for command
1447 gmake libHS.a EXTRA_CC_OPTS="-v"
1452 \subsection{The main @mk/target.mk@ file}
1453 \label{sect_targets}
1455 @target.mk@ contains canned rules for all the standard targets described in
1456 Section~\ref{sect_standard-targets}. It is complicated by the fact
1457 that you don't want all of these rules to be active in every @Makefile@.
1458 Rather than have a plethora of tiny files which you can include selectively,
1459 there is a single file, @target.mk@, which selectively includes rules
1460 based on whether you have defined certain variables in your @Makefile@.
1461 This section explains what rules you get, what variables control them, and
1462 what the rules do. Hopefully, you will also get enough of an idea of what is supposed
1463 to happen that you can read and understand any wierd special cases yourself.
1466 \item{@HS_PROG@.} If @HS_PROG@ is defined, you get rules with the
1469 \item[@HS_PROG@] itself. This rule links @$(OBJS)@ with the Haskell
1470 runtime system to get an executable called @$(HS_PROG)@.
1471 \item[@install@] installs @$(HS_PROG)@ in @$(bindir)@ with the execute bit set.
1474 \item[@C_PROG@] is similar to @HS_PROG@, except that the link step
1475 links @$(C_OBJS)@ with the C runtime system.
1477 \item[@LIBRARY@] is similar to @HS_PROG@, except
1478 that it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@,
1479 and @install@ installs it in @$(libdir)@, with the execute bit not set.
1481 \item[@LIB_DATA@] ...
1482 \item[@LIB_EXEC@] ...
1484 \item[@HS_SRCS@, @C_SRCS@.] If @HS_SRCS@ is defined and non-empty, a rule for
1485 the target @depend@ is included, which generates dependency information for
1486 Haskell programs. Similarly for @C_SRCS@.
1489 All of these rules are ``double-colon'' rules, thus
1491 install :: $(HS_PROG)
1492 ...how to install it...
1494 GNU @make@ treats double-colon rules as separate entities. If there
1495 are several double-colon rules for the same target it takes each in turn
1496 and fires it if its dependencies say to do so. This means that you can,
1497 for example, define both @HS_PROG@ and @LIBRARY@, which will generate two
1498 rules for @install@. When you type @gmake install@ both rules will be fired,
1499 and both the program and the library will be installed, just as you wanted.
1501 \subsection{Recursion}
1502 \label{sect_subdirs}
1504 In leaf @Makefiles@ the variable @SUBDIRS@ is undefined. In non-leaf
1505 @Makefiles@, @SUBDIRS@ is set to the list of sub-directories that contain subordinate
1506 @Makefile@s. {\em It is up to you to set @SUBDIRS@ in the @Makefile@.}
1507 There is no automation here --- @SUBDIRS@ is too important automate.
1509 When @SUBDIRS@ is defined, @target.mk@ includes a rather neat rule for
1510 the standard targets (Section~\ref{sect_standard-targets}) that
1511 simply invokes @make@ recursively in each of the sub-directories.
1513 {\em These recursive invocations are guaranteed to occur in the order in
1514 which the list of directories is specified in @SUBDIRS@.} This guarantee can
1515 be important. For example, when you say @gmake boot@ it can be important
1516 that the recursive invocation of @make boot@ is done in one sub-directory (the include
1517 files, say) before another (the source files).
1518 Generally, put the most independent sub-directory first, and the most dependent
1521 \subsection{Way management}
1524 We sometimes want to build essentially the same system in several different
1525 ``ways''. For example, we want to build @ghc@'s @Prelude@ libraries with
1526 and without profiling, with and without concurrency, and so on, so that
1527 there is an appropriately-built library archive to link with when the user compiles
1529 It would be possible to have a completely separate build tree for each such ``way'',
1530 but it would be horribly bureaucratic, especially since often only parts of the
1531 build tree need to be constructed in multiple ways.
1533 Instead, the @template.mk@ contains some clever magic to allow you to build
1534 several versions of a system; and to control locally how many versions are built
1535 and how they differ. This section explains the magic.
1537 The files for a particular way are distinguished by munging the suffix.
1538 The ``normal way'' is always built, and its files have the standard suffices
1539 @.o@, @.hi@, and so on. In addition, you can build one or more extra ways,
1540 each distinguished by a {\em way tag}. The object files and interface files
1541 for one of these extra ways are distinguished by their suffix. For example,
1542 way @mp@ has files @.mp_o@ and @.mp_hi@. Library archives have their way
1543 tag the other side of the dot, for boring reasons; thus, @libHS_mp.a@.
1545 A @make@ variable called @way@ holds the current way tag. {\em @way@ is only ever
1546 set on the command line of a recursive invocation of @gmake@.} It is
1547 never set inside a @Makefile@. So it is a global constant for any one invocation
1548 of @gmake@. Two other @make@ variables, @way_@ and @_way@ are immediately derived
1549 from @$(way)@ and never altered. If @way@ is not set, then neither are @way_@
1550 and @_way@, and the invocation of @make@ will build the ``normal way''.
1551 If @way@ is set, then the other two variables are set in sympathy.
1552 For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@''
1553 and @_way@ is set to ``@_mp@''. These three variables are then used
1554 when constructing file names.
1556 So how does @make@ ever get recursively invoked with @way@ set? There
1557 are two ways in which this happens:
1559 \item For some (but not all) of the standard targets, when in a leaf sub-directory,
1560 @make@ is recursively invoked for each way tag in @$(WAYS)@. You set @WAYS@ to
1561 the list of way tags you want these targets built for. The mechanism here is
1562 very much like the recursive invocation of @make@ in sub-directories
1563 (Section~\ref{sect_subdirs}).
1565 It is up to you to set @WAYS@ in your @Makefile@; this is how you control
1566 what ways will get built.
1567 \item For a useful collection of targets (such as @libHS_mp.a@, @Foo.mp_o@)
1568 there is a rule which recursively invokes @make@ to make the specified
1569 target, setting the @way@ variable. So if you say @gmake Foo.mp_o@
1570 you should see a recursive invocation @gmake Foo.mp_o way=mp@,
1571 and {\em in this recursive invocation the pattern rule for compiling a Haskell
1572 file into a @.o@ file will match}. The key pattern rules (in @suffix.mk@)
1576 $(HC) $(HC_OPTS) $< -o $@
1582 \subsection{When the canned rule isn't right}
1584 Sometimes the canned rule just doesn't do the right thing. For example, in
1585 the @nofib@ suite we want the link step to print out timing information.
1586 The thing to do here is {\em not} to define @HS_PROG@ or @C_PROG@, and instead
1587 define a special purpose rule in your own @Makefile@.
1588 By using different variable names you will avoid the canned rules being included,
1589 and conflicting with yours.
1592 %************************************************************************
1594 \section[booting-from-C]{Booting/porting from C (\tr{.hc}) files}
1595 \index{building GHC from .hc files}
1596 \index{booting GHC from .hc files}
1598 %************************************************************************
1600 This section is for people trying to get GHC going by using the
1601 supplied intermediate C (\tr{.hc}) files. This would probably be
1602 because no binaries have been provided, or because the machine
1603 is not ``fully supported.''
1605 The intermediate C files are normally made available together with a
1606 source release, please check the announce message for exact directions
1607 of where to find them. If we've haven't made them available or you
1608 can't find them, please ask.
1610 Assuming you've got them, unpack them on top of a fresh source tree.
1611 Then follow the `normal' instructions in
1612 \sectionref{building-from-source} for setting up a build tree and
1613 configuring it. The only extra thing to remember when booting from
1614 \tr{.hc} files is to add the following line to the \tr{build.mk}
1618 GhcWithHscBuiltViaC=YES
1621 and proceed with doing a \tr{make boot} followed by a \tr{make all}.
1623 That's the mechanics of the boot process, but, of course, if you're
1624 trying to boot on a platform that is not supported and significantly
1625 `different' from any of the supported ones, this is only the start
1626 of the adventure...(ToDo: porting tips - stuff to look out for, etc.)
1629 %************************************************************************
1631 \section[build-pitfalls]{Known pitfalls in building Glasgow Haskell}
1632 \index{problems, building}
1633 \index{pitfalls, in building}
1634 \index{building pitfalls}
1636 %************************************************************************
1638 WARNINGS about pitfalls and known ``problems'':
1641 %------------------------------------------------------------------------
1643 One difficulty that comes up from time to time is running out of space
1644 in \tr{/tmp}. (It is impossible for the configuration stuff to
1645 compensate for the vagaries of different sysadmin approaches re temp
1648 The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or
1649 even \tr{setenv TMPDIR .} (or the equivalent incantation with the
1650 shell of your choice).
1652 The best way around it is to say
1656 in your @build.mk@ file.
1657 Then GHC and the other @fptools@ programs will use the appropriate directory
1660 %------------------------------------------------------------------------
1662 In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and
1663 even in \tr{ghc/lib}, you may get a few C-compiler warnings. We think
1666 %------------------------------------------------------------------------
1668 When compiling via C, you'll sometimes get ``warning:
1669 assignment from incompatible pointer type'' out of GCC. Harmless.
1671 %------------------------------------------------------------------------
1673 Similarly, \tr{ar}chiving warning messages like the following are not
1676 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1677 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1681 %------------------------------------------------------------------------
1683 Also harmless are some specialisation messages that you may see when
1684 compiling GHC; e.g.:
1686 SPECIALISATION MESSAGES (Desirable):
1688 {-# SPECIALIZE instance Eq [Class] #-}
1689 {-# SPECIALIZE instance Eq (Class, [Class]) #-}
1690 {-# SPECIALIZE instance Outputable [ClassOp] #-}
1691 {-# SPECIALIZE instance Outputable [Id] #-}
1694 %------------------------------------------------------------------------
1696 In compiling the compiler proper (in \tr{compiler/}), you {\em may} get an
1697 ``Out of heap space'' error message. These
1698 can vary with the vagaries of different systems, it seems. The
1699 solution is simple: (1)~add a suitable \tr{-H} flag to the @<module>_HC_OPTS@
1700 @make@ variable in the appropriate @Makefile@;
1701 (2)~try again: \tr{gmake}.
1702 (Section~\ref{sect_suffix}.)
1704 Alternatively, just cut to the chase scene:
1707 % make EXTRA_HC_OPTS=-H32m # or some nice big number
1710 %------------------------------------------------------------------------
1712 Not too long into the build process, you may get a huge complaint
1715 Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27.
1717 This indicates that your \tr{perl} was mis-installed; the binary is
1718 unable to find the files for its ``built-in'' library. Speak to your
1719 perl installer, then re-try.
1721 %------------------------------------------------------------------------
1723 If you try to compile some Haskell, and you get errors from GCC
1724 about lots of things from \tr{/usr/include/math.h}, then your GCC
1725 was mis-installed. \tr{fixincludes} wasn't run when it should've
1728 As \tr{fixincludes} is now automagically run as part of GCC
1729 installation, this bug also suggests that you have an old GCC.
1732 %------------------------------------------------------------------------
1734 You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
1736 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
1737 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
1739 ? # or, on some machines: ar s $i
1742 We'd be interested to know if this is still necessary.
1744 %------------------------------------------------------------------------
1746 If you end up making documents that involve (La)TeX and/or \tr{tib}
1747 (Simon's favourite), the odds are that something about your/our setup
1748 will reach out and bite you. Yes, please complain; meanwhile,
1749 you can do \tr{make -n whatever.dvi} to see the intended commands,
1750 then try to muddle through, doing them by hand.
1752 %------------------------------------------------------------------------
1754 GHC's sources go through \tr{cpp}
1755 before being compiled, and \tr{cpp} varies a bit from one Unix to another.
1756 One particular gotcha is macro calls like this:
1758 SLIT("Hello, world")
1760 Some \tr{cpp}s treat the comma inside the string as separating two macro arguments,
1763 :731: macro `SLIT' used with too many (2) args
1765 Alas, \tr{cpp} doesn't tell you the offending file!
1767 Workaround: don't put wierd things in string args to \tr{cpp} macros.
1770 \begin{onlystandalone}
1773 \end{onlystandalone}