diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 8 | ||||
| -rw-r--r-- | docs/installing.lit | 1730 |
2 files changed, 1738 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..851469d476 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,8 @@ +TOP = .. +include $(TOP)/mk/boilerplate.mk + +DOC_SRCS = installing.lit release.lit + +SRC_TEXI2HTML_OPTS += -number -monolithic -invisible xbm + +include $(TOP)/mk/target.mk diff --git a/docs/installing.lit b/docs/installing.lit new file mode 100644 index 0000000000..81bdeee2f0 --- /dev/null +++ b/docs/installing.lit @@ -0,0 +1,1730 @@ +% Building and installing the Glasgow Functional Programming Tools Suite +% +% Version 2.02 +% Feb 1997 + + + + +\begin{onlystandalone} +\documentstyle[11pt,literate]{article} +\begin{document} +\title{Building and installing the Glasgow Functional Programming Tools Suite\\ +Version~2.02} +\author{The GHC Team\\ +Department of Computing Science\\ +University of Glasgow\\ +Glasgow, Scotland\\ +G12 8QQ\\ +\\ +Email: glasgow-haskell-\{users,bugs\}\@dcs.gla.ac.uk} +\maketitle +\begin{rawlatex} +\tableofcontents +\end{rawlatex} +\clearpage +\end{onlystandalone} + +This guide is intended for people who want to install or modify +programs from the Glasgow @fptools@ suite (as distinct from those +who merely want to {\em run} them. + +The whole install-and-make system has been completely re-done +between GHC 2.01 and 2.02, so it will be worth your while to re-read this guide +even if you have done so before. + +\section{Getting the Glasgow @fptools@ suite} + +Building the Glasgow tools {\em can} be complicated, mostly because +there are so many permutations of what/why/how, e.g., ``Build Happy +with HBC, everything else with GHC, leave out profiling, and test it +all on the `real' NoFib programs.'' Yeeps! + +Happily, such complications don't apply to most people. A few common +``strategies'' serve most purposes. Pick one and proceed +as suggested: + +\begin{description} +\item[Binary distribution.] If your only purpose is to install +some of the @fptools@ suite then the easiest thing to do is to +get a binary distribution. In the binary distribution everything is +pre-compiled for your particular machine architecture and operating +system, so all you should have to do is install the binaries and libraries +in suitable places. {\em Need pointer to info about doing binary installation.} + +A binary distribution may not work for you for two reasons. +First, we may not have built the suite for the particular +architecture/OS platform you want. That may be due to lack of time and +energy (in which case you can get a source distribution and build from it; +see below). Alternatively, it may be because we havn't yet ported the +suite to your architecture, in which case you are considerably worse off. + +The second reason a binary distribution may not be what you want is +if you want to read or modify the souce code. + +\item[Source distribution.] +You have a supported +platform, but (a)~you like the warm fuzzy feeling of compiling things +yourself; (b)~you want to build something ``extra''---e.g., a set of +libraries with strictness-analysis turned off; or (c)~you want to hack +on GHC yourself. + +A source distribution contains complete sources for the @fptools@ suite. +Not only that, but the more awkward machine-independent steps are done +for you. For example, if you don't have @flex@ you'll it convenient that +the source distribution contains the result of running @flex@ on the +lexical analyser specification. If you don't want to alter the lexical +analyser then this saves you having to find and install @flex@. +You will still need a working version of GHC on your machine in order to +compile (most of) the sources, however. + + +\item[Build GHC from intermediate C \tr{.hc} files:] +You need a working GHC to use a source distribution. What if you don't have a working GHC? +Then you have no choice but to ``bootstrap'' up from the +intermediate C (\tr{.hc}) files that we provide. +Building GHC on an unsupported platform falls into this category. +Please see \sectionref{booting-from-C}. + +NB: For GHC~2.01, bootstrapping from \tr{.hc} files means you will get +an all-2.01 system---possibly unduly slow. Building with GHC~0.29 +will get you a faster compiler... + +Once you have built GHC, you can build the other Glasgow tools with +it. + +In theory, you can build GHC with another Haskell compiler (e.g., +HBC). We havn't tried to do this for ages and it almost certainly +doesn't work any more. + +\item[The CVS repository.] +We make source distributions at the same time as binary distributions; +i.e. infrequently. They should, however, be pretty throughly tested. +If you want more up-to-the minute (but less tested) source code then you +need to get access to our CVS repository. + +All the @fptools@ source code is held in a CVS repository. +CVS is a pretty good source-code control system, and best of all it works over the network. + +The repository holds source code only. It holds no mechanically generated +files at all. So if you check out a source tree from CVS you will need +to install every utility so that you can build all the derived files +from scratch. + +Giving you access to the repository entails some systems administration +at our end; and we are a bit nervous about being submerged in bug reports +about our current working copy (which is, by definition, in flux). So +we are a bit cautious about offering CVS access. Feel free to ask though! +\end{description} + +If you are going to do any building from sources (either from a source +distribution or the CVS repository) then you need to read all of this manual in detail. + + +%************************************************************************ +%* * +\section{Things to check before you start typing} +%* * +%************************************************************************ + +Here's a list of things to check before you get started. +\begin{enumerate} +\item +\index{disk space needed} +Disk space needed: About 30MB (five hamburgers' worth) of disk space +for the most basic binary distribution of GHC; more for some +platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent +Haskell libraries) might take you to 8--10 hamburgers. + +You'll need over 100MB (say, 20 hamburgers' worth) if you need to +build the basic stuff from scratch. + +I don't yet know the disk requirements for the non-GHC tools. + +All of the above are {\em estimates} of disk-space needs. + +\item +Use an appropriate machine, compilers, and things. + +SPARC boxes and DEC Alphas running OSF/1 are fully supported. +Linux, MIPS, and HP boxes are in pretty good shape. +\Sectionref{port-info} gives the full run-down on ports or lack +thereof. + +\item +Be sure that the ``pre-supposed'' utilities are installed. +Section~\ref{sect_std-utils} elaborates. + +\item +If you have any problem when building or installing the Glasgow tools, +please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If +you feel there is still some shortcoming in our procedure or +instructions, please report it. + +For GHC, please see the bug-reporting section of the User's guide +(separate document), to maximise the usefulness of your report. + +If in doubt, please send a message to +\tr{glasgow-haskell-bugs@dcs.gla.ac.uk}. +\end{enumerate} + + +%************************************************************************ +%* * +\section[port-info]{What machines the Glasgow tools, version~2.01, run on} +\index{ports, GHC} +\index{GHC ports} +\index{supported platforms} +\index{platforms, supported} +%* * +%************************************************************************ + +The main question is whether or not the Haskell compiler (GHC) runs on +your platform. + +A ``platform'' is a +architecture/manufacturer/operating-system combination, +such as @sparc-sun-solaris2.5.1@. Other common ones are +@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@, +@i386-unknown-solaris2@, @i386-unknown-freebsd@, +@m68k-sun-sunos4@, @mips-sgi-irix5@, +@sparc-sun-sunos4@, @sparc-sun-solaris2@. + +Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not +work on all machines for which basic Haskell compiling is supported. + +Some libraries may only work on a limited number of platforms; for +example, a sockets library is of no use unless the operating system +supports the underlying BSDisms. + +%************************************************************************ +%* * +\subsection{What platforms the Haskell compiler (GHC) runs on} +%* * +%************************************************************************ +\index{fully-supported platforms} +\index{native-code generator} +\index{registerised ports} +\index{unregisterised ports} + +The GHC hierarchy of Porting Goodness: (a)~Best is a native-code +generator; (b)~next best is a ``registerised'' +port; (c)~the bare minimum is an ``unregisterised'' port. +``Unregisterised'' is so terrible that we won't say more about it. + +We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas +running OSF/1~V2.0, so those are the ``fully-supported'' platforms, +unsurprisingly. Both have native-code generators, for quicker +compilations. The native-code generator for iX86 platforms (e.g., +Linux ELF) is {\em nearly} working; but is not turned on by default. + +Here's everything that's known about GHC ports, as of 2.01. We +identify platforms by their ``canonical GNU-style'' names. + +Note that some ports are fussy about which GCC version you use; or +require GAS; or ... + +\begin{description} +%------------------------------------------------------------------- +\item[\tr{alpha-dec-osf1}:] +\index{alpha-dec-osf1: fully supported} +(We have OSF/1 V2.0.) Fully supported, including native-code generator. +We recommend GCC 2.6.x or later. + +%------------------------------------------------------------------- +\item[\tr{sparc-sun-sunos4}:] +\index{sparc-sun-sunos4: fully supported} +Fully supported, including native-code generator. + +%------------------------------------------------------------------- +\item[\tr{sparc-sun-solaris2}:] +\index{sparc-sun-solaris2: fully supported} +Fully supported, including native-code generator. A couple of quirks, +though: (a)~the profiling libraries are bizarrely huge; (b)~the +default \tr{xargs} program is atrociously bad for building GHC +libraries (see \sectionref{Pre-supposed} for details). + +%------------------------------------------------------------------- +\item[HP-PA box running HP/UX 9.x:] +\index{hppa1.1-hp-hpux: registerised port} +Works registerised. No native-code generator. +For GCC, you're best off with one of the Utah releases of +GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}. +We think a straight GCC 2.7.x works, too. + +Concurrent/Parallel Haskell probably don't work (yet). +\index{hppa1.1-hp-hpux: concurrent---no} +\index{hppa1.1-hp-hpux: parallel---no} + +%------------------------------------------------------------------- +\item[\tr{i386-*-linux} (PCs running Linux---ELF format):] +\index{i386-*-linux: registerised port} +GHC~2.01 works registerised. +You {\em must} have GCC 2.7.x or later. +The iX86 native-code generator is {\em nearly} there, but it +isn't turned on by default. + +Profiling works, and Concurrent Haskell works. +\index{i386-*-linux: profiling---yes} +\index{i386-*-linux: concurrent---yes} +Parallel Haskell probably works. +\index{i386-*-linux: parallel---maybe} + +On old Linux a.out systems: should be the same. +\index{i386-*-linuxaout: registerised port} + +%------------------------------------------------------------------- +\item[\tr{i386-*-*bsd} (PCs running FreeBSD (and NetBSD?):] +\index{i386-*-freebsd: registerised port} +GHC~2.01 works registerised. Supports same set of bundles +as the above. + +\index{i386-*-freebsd: profiling---yes} +\index{i386-*-freebsd: concurrent---yes} +\index{i386-*-freebsd: parallel---maybe} + +%------------------------------------------------------------------- +\item[\tr{i386-unknown-cygwin32}:] +\index{i386-unknown-cygwin32: fully supported} +Fully supported under Win95/NT, including a native +code generator. Requires the @cygwin32@ compatibility library and +a healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.) +Profiling works, so does Concurrent Haskell. +\index{i386-*-cygwin32: profiling---yes} +\index{i386-*-cygwin32: concurrent---yes} + +% ToDo: more documentation on this is reqd here. + +%------------------------------------------------------------------- +\item[\tr{mips-sgi-irix5}:] +\index{mips-sgi-irix5: registerised port} +GHC~2.01 works registerised (no native-code generator). +I suspect any GCC~2.6.x (or later) is OK. The GCC that I used +was built with \tr{--with-gnu-as}; turns out that is important! + +Concurrent/Parallel Haskell probably don't work (yet). +Profiling might work, but it is untested. +\index{mips-sgi-irix5: concurrent---no} +\index{mips-sgi-irix5: parallel---no} +\index{mips-sgi-irix5: profiling---maybe} + +%------------------------------------------------------------------- +\item[\tr{m68k-apple-macos7} (Mac, using MPW):] +\index{m68k-apple-macos7: historically ported} +Once upon a time, David Wright in Tasmania has actually +gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow. +You may be able to get Thomson's from here. (Not sure that it will +excite you to death, but...) + +No particularly recent GHC is known to work on a Mac. + +%------------------------------------------------------------------- +\item[\tr{m68k-next-nextstep3}:] +\index{m68k-next-nextstep3: historically ported} +Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19. +There's probably a little bit-rot since then, but otherwise it should +still be fine. Had a report that things were basically OK at 0.22. + +Concurrent/Parallel Haskell probably won't work (yet). +\index{m68k-next-nextstep3: concurrent---no} +\index{m68k-next-nextstep3: parallel---no} + +%------------------------------------------------------------------- +\item[\tr{m68k-sun-sunos4} (Sun3):] +\index{m68k-sun-sunos4: registerised port} +GHC~2.01 hasn't been tried on a Sun3. GHC~0.26 worked registerised. +No native-code generator. + +Concurrent/Parallel Haskell probably don't work (yet). +\index{m68k-sun-sunos4: concurrent---no} +\index{m68k-sun-sunos4: parallel---no} +\end{description} + +%************************************************************************ +%* * +\subsection{What machines the other tools run on} +%* * +%************************************************************************ + +Unless you hear otherwise, the other tools work if GHC works. + +Haggis requires Concurrent Haskell to work. +\index{Haggis, Concurrent Haskell} + + +%************************************************************************ +%* * +\section[installing-bin-distrib]{Installing from binary distributions} +\index{binary installations} +\index{installation, of binaries} +%* * +%************************************************************************ + +Installing from binary distributions is easiest, and recommended! +(Why binaries? Because GHC is a Haskell compiler written in Haskell, +so you've got to ``bootstrap'' it, somehow. We provide +machine-generated C-files-from-Haskell for this purpose, but it's +really quite a pain to use them. If you must build GHC from its +sources, using a binary-distributed GHC to do so is a sensible way to +proceed. For the other @fptools@ programs, many are written in Haskell, +so binary distributions allow you to install them without having a Haskell compiler.) + + +\subsection{Bundle structure} + +Binary distributions come in ``bundles,''\index{bundles of binary stuff} +one bundle per file called \tr{<bundle>-<platform>.tar.gz}. +(See Section~\ref{port-info} for what a platform is.) +Suppose that you untar a binary-distribution bundle, thus: +\begin{verbatim} + % cd /your/scratch/space + % gunzip < ghc-2.02-sun-sparc-solaris2.tar.gz | tar xvf - +\end{verbatim} +Then you should find a single directory, @fptools@, with the following +structure: +\begin{description} +\item[@Makefile.in@] the raw material from which the @Makefile@ will be made (\sectionref{sect_install}). +\item[@configure@] the configuration script (\sectionref{sect_install}). +\item[@README@] Contains this file summary. +\item[@INSTALL@] Contains this description of how to install the bundle. +\item[@ANNOUNCE-<bundle>@] The announcement message for the bundle. +\item[@NEWS-<bundle>@] release notes for the bundle -- a longer version of @ANNOUNCE@. +\item[@bin/<platform>/@] contains platform-specific executable files to be invoked +directly by the user. These are the files that must end up in your path. +\item[@lib/<platform>@] contains platform-specific support files for the installation. +Typically there is a subdirectory for each @fptools@ project, whose name is +the name of the project with its version number. +For example, for GHC 2.02 there would be a sub-directory @ghc-2.02/@. + +These sub-directories have the following general structure: +\begin{description} +\item[@libHS.a@ etc:] supporting library archives. +\item[@ghc-iface.prl@ etc:] support scripts. +\item[@import/@] Interface files (@.hi@) for the prelude. +\item[@include/@] A few C @#include@ files. +\end{description} + +\item[@share/@] contains platform-independent support files for the installation. +Again, there is a sub-directory for each @fptools@ project. + +\item[@info/@] contains Emacs info documentation files (one sub-directory per project). +\item[@html/@] contains HTML documentation files (one sub-directory per project). +\item[@man/@] contains Unix manual pages. +\end{description} +This structure is designed so that you can unpack multiple bundles (including +ones from different releases or platforms) into a single @fptools@ directory: +\begin{verbatim} + % cd /your/scratch/space + % gunzip < ghc-2.02-sun-sparc-solaris2.tar.gz | tar xvf - + % gunzip < happy-1.09-sun-sparc-sunos4.tar.gz | tar xvf - +\end{verbatim} +When you do multiple unpacks like this, the top level @Makefile@, @README@, +and @INSTALL@ get overwritten each time. That's fine -- they should be the same. +Likewise, the @ANNOUNCE-<bundle>@ and @NEWS-<bundle>@ files will be duplicated +across multiple platforms, so they will be harmlessly overwritten when you do +multiple unpacks. +Finally, the @share/@ stuff will get harmlessly overwritten when you do multiple +unpacks for one bundle on different platforms. + +\subsection[sect_install]{Installing} + +OK, so let's assume that you have unpacked your chosen bundles into +a scratch directory @fptools@. What next? Well, you will at least need +to run the @configure@ script by changing your directory to @fptools@. +That should convert @Makefile.in@ to @Makefile@. + +You can now either start using the tools {\em in-situ} without going +through any installation process, just type @make config@ to set the +tools up for this (you have to be in the @fptools@ directory). You'll +also want to add the path which @make@ echoes to your @PATH@ +environment variable. This option is useful if you simply want to try +out the package or you don't have the necessary priviledges (or +inclination) to properly install the tools locally. Note that if you +do decide to install the package `properly' at a later date, you have +to go through the installation steps that +follows. + +To install an @fptools@ package, you'll have to do the following: + +\begin{enumerate} +\item Edit the @Makefile@ and check the settings of the following variables: +\begin{description} +\item[@platform@] the platform you are going to install for. +\item[@bindir@] the directory in which to install user-invokable binaries. +\item[@libdir@] the directory in which to install platform-dependent support files. +\item[@datadir@] the directory in which to install platform-independent support files. +\item[@infodir@] the directory in which to install Emacs info files. +\item[@htmldir@] the directory in which to install HTML documentation. +\item[@dvidir@] the directory in which to install DVI documentation. +\end{description} +The values for these variables can be set through invocation of the +@configure@ script that comes with the distribution, but doing an optical +diff to see if the values match your expectations is always a Good Idea. + +{\em Instead of running @configure@, it is perfectly OK to copy +@Makefile.in@ to @Makefile@ and set all these variables directly +yourself. But do it right!} + +\item Run @make install@. This {\em should} works with ordinary Unix +@make@ -- no need for fancy stuff like GNU @make@. + +\item \tr{rehash} (t?csh users), so your shell will see the new stuff +in your bin directory. + +\item +Once done, test your ``installation'' as suggested in +\sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you +can see exactly what pathnames it's using. + +If things don't work as expected, check the list of know pitfalls +\sectionref{build-pitfalls}. +\end{enumerate} + +When installing the user-invokable binaries, this installation +procedure will install, say, @GHC@ version 2.02 as @ghc-2.02@. It +will also make a link (in the binary installation directory) from +@ghc@ to @ghc-2.02@. If you install multiple versions of GHC then the +last one ``wins'', and ``@ghc@'' will invoke the last one installed. +You can change this manually if you want. But regardless, @ghc-2.02@ +should always invoke @GHC@ version 2.02. + +\subsection{What bundles there are} + +There are plenty of ``non-basic'' GHC bundles. The files for them are +called \tr{ghc-2.01-<bundle>-<platform>.tar.gz}, where the +\tr{<platform>} is as above, and \tr{<bundle>} is one of these: +\begin{description} +\item[\tr{prof}:] Profiling with cost-centres. You probably want this. + +\item[\tr{conc}:] Concurrent Haskell features. You may want this. + +\item[\tr{par}:] Parallel Haskell features (sits on top of PVM). +You'll want this if you're into that kind of thing. + +\item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator +(hmm... mainly for implementors). + +\item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed +information about ``what happened when I ran this program''---really +for implementors. + +\item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell. + +\item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell. +\end{description} + +One likely scenario is that you will grab {\em three} binary +bundles---basic, profiling, and concurrent. + + + +%************************************************************************ +%* * +\subsection[GHC_test]{Test that GHC seems to be working} +\index{testing a new GHC} +%* * +%************************************************************************ + +The way to do this is, of course, to compile and run {\em this} program +(in a file \tr{Main.hs}): +\begin{verbatim} +main = putStr "Hello, world!\n" +\end{verbatim} + +First, give yourself a convenient way to execute the driver script +\tr{ghc/driver/ghc}, perhaps something like... +\begin{verbatim} +% ln -s /local/src/ghc-2.01/ghc/driver/ghc ~/bin/alpha/ghc +% rehash +\end{verbatim} + +Compile the program, using the \tr{-v} (verbose) flag to verify that +libraries, etc., are being found properly: +\begin{verbatim} +% ghc -v -o hello Main.hs +\end{verbatim} + +Now run it: +\begin{verbatim} +% ./hello +Hello, world! +\end{verbatim} + +Some simple-but-profitable tests are to compile and run the +notorious \tr{nfib} program, using different numeric types. Start +with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float}, +\tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code +for this is distributed in \tr{ghc/misc/examples/nfib/}. + +For more information on how to ``drive'' GHC, +either do \tr{ghc -help} or consult the User's Guide (distributed in +\tr{ghc/docs/users_guide}). + + +%************************************************************************ +%* * +\section[Pre-supposed]{Installing pre-supposed utilities} +\index{pre-supposed utilities} +\index{utilities, pre-supposed} +%* * +%************************************************************************ + +\label{sect_std-utils} + +Here are the gory details about some utility programs you may need; +\tr{perl} and \tr{gcc} are the only important ones. (PVM is important +if you're going for Parallel Haskell.) The \tr{configure} script will +tell you if you are missing something. + +\begin{description} +\item[Perl:] +\index{pre-supposed: Perl} +\index{Perl, pre-supposed} +{\em You have to have Perl to proceed!} Perl is a language quite good +for doing shell-scripty tasks that involve lots of text processing. +It is pretty easy to install. + +(Perl~5 is the current version; GHC might be Perl~4 friendly, we've +run into some trouble with our scripts on \tr{alpha-dec-osf\{1,2\}} +using Perl~4 (patchlevel 36)) + +Perl should be put somewhere so that it can be invoked by the \tr{#!} +script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred; +we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should +be less than 32 characters long. + +\item[GNU C (\tr{gcc}):] +\index{pre-supposed: GCC (GNU C compiler)} +\index{GCC (GNU C compiler), pre-supposed} +The current version is 2.7.2. It has a bug that it ticked if you +compile the @gmp@ library without the @-O@ flag. So the Makefile in +there has the @-O@ flag switched on! Otherwise, 2.7.2 has no problems that we know of. + +If your GCC dies with ``internal error'' on some GHC source file, +please let us know, so we can report it and get things improved. +(Exception: on \tr{iX86} boxes---you may need to fiddle with GHC's +\tr{-monly-N-regs} option; ask if confused...) + +\item[PVM version 3:] +\index{pre-supposed: PVM3 (Parallel Virtual Machine)} +\index{PVM3 (Parallel Virtual Machine), pre-supposed} +PVM is the Parallel Virtual Machine on which Parallel Haskell programs +run. (You only need this if you plan to run Parallel Haskell. +Concurent Haskell, which runs concurrent threads on a uniprocessor) +doesn't need it.) +Underneath PVM, you can have (for example) a network of +workstations (slow) or a multiprocessor box (faster). + +The current version of PVM is 3.3.11; we use 3.3.7. It is readily available on +the net; I think I got it from \tr{research.att.com}, in \tr{netlib}. + +A PVM installation is slightly quirky, but easy to do. Just follow +the \tr{Readme} instructions. + +\item[\tr{xargs} on Solaris2:] +\index{xargs, presupposed (Solaris only)} +\index{Solaris: alternative xargs} +The GHC libraries are put together with something like: +\begin{verbatim} +find bunch-of-dirs -name '*.o' -print | xargs ar q ... +\end{verbatim} +Unfortunately the Solaris \tr{xargs} (the shell-script equivalent +of \tr{map}) only ``bites off'' the \tr{.o} files a few at a +time---with near-infinite rebuilding of the symbol table in +the \tr{.a} file. + +The best solution is to install a sane \tr{xargs} from the GNU +findutils distribution. You can unpack, build, and install the GNU +version in the time the Solaris \tr{xargs} mangles just one GHC +library. + +\item[\tr{bash} (Parallel Haskell only):] +\index{bash, presupposed (Parallel Haskell only)} +Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles'' +to PostScript, is written in Bash (GNU's Bourne Again shell). +This bug will be fixed (someday). + +\item[Makeindex:] +\index{pre-supposed: makeindex} +\index{makeindex, pre-supposed} +You won't need this unless you are re-making our documents. Makeindex +normally comes with a \TeX{} distribution, but if not, we can provide +the latest and greatest. + +\item[Tgrind:] +\index{pre-supposed: tgrind} +\index{tgrind, pre-supposed} +This is required only if you remake lots of our documents {\em and} +you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate +programming), to do ``fancy'' typesetting of your code. {\em +Unlikely.} + +\item[Flex:] +\index{pre-supposed: flex} +\index{flex, pre-supposed} +This is a quite-a-bit-better-than-Lex lexer. Used in the +literate-programming stuff. You won't need it unless you're hacking +on some of our more obscure stuff. + +\item[Yacc:] +\index{pre-supposed: non-worthless Yacc} +\index{Yacc, pre-supposed} +If you mess with the Haskell parser, you'll need a Yacc that can cope. +The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK; +Berkeley yacc, \tr{byacc}, is not OK. + +\item[@sed@] +\index{pre-supposed: sed} +\index{sed, pre-supposed} +You need a working @sed@ if you are going to build from sources. +The build-configuration stuff needs it. +GNU sed version 2.0.4 is no good! It has a bug in it that is tickled by the +build-configuration. 2.0.5 is ok. Others are probably ok too +(assuming we don't create too elaborate configure scripts..) +\end{description} + +Two @fptools@ projects are worth a quick note at this point, because +they are useful for all the others: +\begin{itemize} +\item @glafp-utils@ contains several small utilities +which aren't particularly Glasgow-ish, but which are sometimes not +available on Unix systems. + +\item @literate@ contains the Glasgow-built tools for generating +documentation. (The unoriginal idea is to be able to generate @latex@, @info@, +and program code from a single source file.) To get anywhere you'll +need at least @lit2pgm@, either from the @literate@ project, or +because it's already installed on your system. +\end{itemize} + + + + +%************************************************************************ +%* * +\section{Building from source} +%* * +%************************************************************************ + +You've been rash enough to want to build some of +the Glasgow Functional Programming tools (GHC, Happy, +nofib, etc) from source. You've slurped the source, +from the CVS repository or from a source distribution, and +now you're sitting looking at a huge mound of bits, wondering +what to do next. + +Gingerly, you type @make all@. Wrong already! + +This rest of this guide is intended for duffers like me, who aren't really +interested in Makefiles and systems configurations, but who need +a mental model of the interlocking pieces so that they can +make them work, extend them consistently when adding new +software, and lay hands on them gently when they don't work. + +\subsection{Your source tree} + +The source code is held in your {\em source tree}. +The root directory of your source tree {\em must} +contain the following directories and files: +\begin{itemize} +\item @Makefile@: the root Makefile. +\item @mk/@: the directory that contains the +main Makefile code, shared by all the +@fptools@ software. +\item @configure.in@: a file that tells the GNU configuration +tools what @fptools@ needs to know about the host platform and +operating system. +\end{itemize} +All the other directories are individual {\em projects} of the +@fptools@ system --- for example, the Glasgow Haskell Compiler (@ghc@), +the Happy parser generator (@happy@), the @nofib@ benchmark stuite, +and so on. +You can have zero or more of these. Needless to say, some of them +are needed to build others. For example, you need @happy@ to build +@ghc@. You can either grab @happy@ too, or else you can use +an version of @happy@ that's already installed on your system, or +grab a binary distribution of @happy@ and install it. + +The important thing to remember is that even if you want only +one project (@happy@, say), you must have a source tree +whose root directory contains @Makefile@, +@mk/@, @configure.in@, and the project(s) you +want (@happy/@ in this case). You cannot get by with +just the @happy/@ directory. + +\subsection{Build trees} + +While you can build a system in the source tree, we don't recommend it. +We often want to build multiple versions of our software +for different architectures, or with different options (e.g. profiling). +It's very desirable to share a single copy of the source code among +all these builds. + +So for every source tree we have zero or more {\em build trees}. +Each build tree is initially an exact copy of the source tree, +except that each file is a symbolic link to the source file, +rather than being a copy of the source file. There are ``standard'' +Unix utilities that make such copies, so standard that they go by +different names: @lndir@, @mkshadowdir@ are two. + +The build +tree does not need to be anywhere near the source tree in the +file system. +Indeed, one advantage of separating the build tree from the source +is that the build tree can be placed in a non-backed-up partition, +saving your systems support people from backing up untold megabytes +of easily-regenerated, and rapidly-changing, gubbins. The golden rule is +that (with a single exception -- Section~\ref{sect_build-config}) +{\em absolutely +everything in the build tree is either a symbolic link to the source +tree, or else is mechanically generated}. It should be perfectly +OK for your build tree to vanish overnight; an hour or two compiling +and you're on the road again. + +You need to be a bit careful, though, that any new files you create +(if you do any development work) are in the source tree, not a build tree! + +Like the source tree, the top level of your build tree must (a linked copy of) +the root directory of the @fptools@ suite. +Inside Makefiles, the root of your build tree is called @$(FPTOOLS_TOP)@. +In the rest of this document path names are relative to @$(FPTOOLS_TOP)@ +unless otherwise stated. For example, the file @ghc/mk/target.mk@ is +actually @$(FPTOOLS_TOP)/ghc/mk/target.mk@. + + +\subsection{Getting the build you want} +\label{sect_build-config} + +When you build @fptools@ you will be compiling code +on a particular {\em host platform}, +to run on a particular {\em target platform} (usually the same +as the host platform)\index{platform}. The difficulty is +that there are minor differences between different platforms; +minor, but enough that the code needs to be a bit different +for each. There are some big differences too: for +a different architecture we need to build GHC with a different +native-code generator. + +There are also knobs you can turn to control how the @fptools@ +software is built. For example, you might want to build GHC +optimised (so that it runs fast) or unoptimised (so that you can +compile it fast after you've modified it. +Or, you might want to compile it with debugging on (so that +extra consistency-checking code gets included) or off. And so on. + +All of this stuff is called the {\em configuration} of your build. +You set the configuration using an exciting two-step process. +\begin{description} +\item[Step 1: system configuration.] This is easy, provided you +have the programs mentioned in Section~\ref{sect_std-utils}. Just +@cd@ to @$(FPTOOLS)@ and say @gmake configure@. This +command does three things: +\begin{itemize} +\item +It runs a GNU program called @autoconf@, which +converts @$(FPTOOLS)/configure.in@ to a shell script +called @$(FPTOOLS)/configure@. + +This step is completely platform-independent; it just means +that the human-written file (@configure.in@) can be short, although +the resulting shell script, @configure@ is long. + +\item It runs a second GNU program called @autoheader@, which converts +@$(FPTOOLS)/configure.in@ to @$(FPTOOLS)/mk/config.h.in@. +Again, this step is platform-independent. + +\item It then runs the newly-created @configure@ script. @configure@'s mission +is to scurry round your computer working out what architecture it has, +what operating system, whether it has the @vfork@ system call, +where @yacc@ is kept, whether @gcc@ is available, where various +obscure @#include@ files are, whether it's a leap year, and +what the systems manager had for lunch. +It communicates these snippets of information in two ways: +\begin{itemize} +\item It translates @mk/config.mk.in@ to @mk/config.mk@, +substituting for things between ``{\tt @@@@}'' brackets. So, +``{\tt @@HaveGcc@@}'' will be replaced by ``@YES@'' or ``@NO@'' +depending on what @configure@ finds. +@mk/config.mk@ is included by every Makefile (directly or indirectly), +so the configuration information is thereby communicated to +all Makefiles. + +\item It translates @mk/config.h.in@ to @mk/config.h@. +The latter is @#include@d by various C programs, which +can thereby make use of configuration information. +\end{itemize} +\end{itemize} + + +\item[Step 2: build configuration.] Next, you say how this build +of @fptools@ is to differ from the standard defaults by creating a new +file @mk/build.mk@ +{\em in the build tree}. This file is the one and only +file you edit in the build tree, precisely because it says how +this build differs from the source. (Just in case your build tree +does die, you might want to keep a private directory of @build.mk@ files, +and use a symbolic link in each build tree to point to the appropriate one.) +So @mk/build.mk@ never +exists in the source tree --- you create one in each build tree +from the template. We'll discuss what to put in it shortly. +\end{description} +And that's it for configuration. Simple, eh? + +What do you put in your build-specific configuration +file @mk/build.mk@? {\em For almost all purposes all you will do is +put make variable definitions that override those in @mk/config.mk.in@}. +The whole point of @mk/config.mk.in@ --- and its derived +counterpart @mk/config.mk@ --- is to define the build configuration. It is heavily +commented, as you will see if you look at it. +So generally, what you do is edit @mk/config.mk.in@ (read-only), and add definitions +in @mk/build.mk@ that override any of the @config.mk@ definitions that you +want to change. (The override occurs because the main boilerplate file, +@mk/boilerplate.mk@, includes @build.mk@ after @config.mk@.) + +For example, @config.mk.in@ contains the definition: +\begin{verbatim} + SUBDIRS = glafp-utils literate ghc +\end{verbatim} +The accompanying comment explains that this is the list of enabled +projects; that is, if (after configuring) you type @gmake all@ +in @FPTOOLS_TOP@ three specified projects will be made. +If you want to add @happy@, you can add this line to @build.mk@: +\begin{verbatim} + SUBDIRS += happy +\end{verbatim} +or, if you prefer, +\begin{verbatim} + SUBDIRS = glafp-utils literate ghc happy +\end{verbatim} +(GNU @make@ allows existing definitions to have new text appended using +the ``@+=@'' operator, which is quite a convenient feature.) + +When reading @config.mk.in@, remember that anything between ``{\tt @@...@@}'' signs +is going to be substituted by @configure@ later. You {\em can} override +the resulting definition if you want, +but you need to be a bit surer what you are doing. +For example, there's a line that says: +\begin{verbatim} + YACC = @Yacc@ +\end{verbatim} +This defines the Make variables @YACC@ to the pathname for a Yacc that +@configure@ finds somewhere. If you have your own pet Yacc you want +to use instead, that's fine. Just add this line to @mk/build.mk@: +\begin{verbatim} + YACC = myyacc +\end{verbatim} +You do not {\em have} to have a @mk/build.mk@ file at all; if you don't, +you'll get all the default settings from @mk/config.mk.in@. + + +\subsection{The story so far} + +Let's summarise the steps you need to carry to get yourself +a fully-configured build tree from scratch. + +\begin{enumerate} +\item Get your source tree from somewhere (CVS repository or +source distribution). Say you call the root directory +@myfptools@ (it does not have to be called @fptools@). + +\item Use @lndir@ or @mkshadowdir@ to create a build tree. +\begin{verbatim} + cd myfptools + mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 +\end{verbatim} +You probably want to give the build tree a name that +suggests its main defining characteristic (in your mind at least), +in case you later add others. + +\item Change directory to the build tree. Everything is going +to happen there now. +\begin{verbatim} + cd /scratch/joe-bloggs/myfptools-sun4 +\end{verbatim} +\item Do system configuration: +\begin{verbatim} + gmake configure +\end{verbatim} +\item Create the file @mk/build.mk@, +adding definitions for your desired configuration options. +\begin{verbatim} + emacs mk/build.mk +\end{verbatim} +\end{enumerate} +You can make subsequent changes to @mk/build.mk@ as often +as you like. You do not have to run any further configuration +programs to make these changes take effect. +In theory you should, however, say @gmake clean@, @gmake all@, +because configuration option changes could affect anything --- but in practice you are likely to know what's affected. + +\subsection{Making things} + +At this point you have made yourself a fully-configured build tree, +so you are ready to start building real things. + +The first thing you need to know is that +{\em you must use GNU @make@, usually called @gmake@, not standard Unix @make@}. +If you use standard Unix @make@ you will get all sorts of error messages +(but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities +extensively. + +\subsection[sect_standard-targets]{Standard targets} + +In any directory you should be able to make the following: +\begin{description} +\item[@boot@:] does the one-off preparation required to get ready +for the real work. Notably, it does @gmake depend@ in all directories +that contain programs. But @boot@ does more. For example, you can't +do @gmake depend@ in a directory of C program until you have converted +the literate @.lh@ header files into standard @.h@ header files. Similarly, you convert a literate file to illiterate +form until you have built the @literate@ tools. @boot@ takes care of these +inter-directory dependencies. + +You should say @gmake boot@ right after configuring your build tree. + +\item[@all@:] makes all the final target(s) for this Makefile. +Depending on which directory you are in a ``final target'' +may be an executable program, a library archive, a shell script, +or a Postscript file. +Typing @gmake@ alone is generally the same as typing @gmake all@. + +\item[@install@:] installs the things built by @all@. Where does it +install them? That is specified by @mk/config.mk.in@; you can +override it in @mk/build.mk@. + +\item[@uninstall@:] reverses the effect of @install@. + +\item[@clean@:] remove all easily-rebuilt files. + +\item[@veryclean@:] remove all files that can be rebuilt at all. +There's a danger here that you may remove a file that needs a more +obscure +utility to rebuild it (especially if you started from a source +distribution). + +\item[@check@:] run the test suite. +\end{description} +All of these standard targets +automatically recurse into sub-directories. +Certain other standard targets do not: +\begin{description} +\item[@configure@:] is only available in the root directory @$(FPTOOLS)@; +it has been discussed in Section~\ref{sect_build-config}. + +\item[@depend@:] make a @.depend@ file in each directory that needs +it. This @.depend@ file contains mechanically-generated dependency +information; for example, suppose a directory contains a Haskell +source module @Foo.lhs@ which imports another module @Baz@. +Then the generated @.depend@ file will contain the dependency: +\begin{verbatim} + Foo.o : Baz.hi +\end{verbatim} +which says that the object file @Foo.o@ depends on the interface +file @Baz.hi@ generated by compiling module @Baz@. +The @.depend@ file is automatically included by every Makefile. + +\item[@binary-dist@:] make a binary distribution. + +\item[@dist@:] make a source distribution. +\end{description} + +\subsection{Other targets} + +Most @Makefiles@ have targets other than these. You can find +this out by looking in the @Makefile@ itself. + + + + +%************************************************************************ +%* * +\section{The @Makefile@ architecture} +%* * +%************************************************************************ + + +@make@ is great if everything works --- you type @gmake install@ and, lo, +the right things get compiled and installed in the right places. +Our goal is to make this happen often, but somehow it often doesn't; +instead +some wierd error message eventually emerges from the bowels of a directory +you didn't know existed. + +The purpose of this section is to give you a road-map to help you figure +out what is going right and what is going wrong. + +\subsection{A small project} + +To get started, let us look at the @Makefile@ for an imaginary small +@fptools@ project, @small@. Each project in @fptools@ has its own +directory in @FPTOOLS_TOP@, so the @small@ project will have its own +directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there +will be a @Makefile@, looking something like this: +\begin{verbatim} + # Makefile for fptools project "small" + + TOP = .. + include $(TOP)/mk/boilerplate.mk + + SRCS = $(wildcard *.lhs) $(wildcard *.c) + HS_PROG = small + + include $(TOP)/target.mk +\end{verbatim} +This @Makefile@ has three sections: +\begin{enumerate} +\item The first section includes\footnote{One of the +most important features of GNU @make@ that we use is the ability +for a @Makefile@ to include another named file, very like @cpp@'s @#include@ directive.} +a file of ``boilerplate'' code from the +level above (which in this case will be @FPTOOLS_TOP/mk/boilerplate.mk@). +As its name suggests, @boilerplate.mk@ consists of a large quantity of standard +@Makefile@ code. We discuss this boilerplate in more detail in Section~\ref{sect_boiler}. + +Before the @include@ statement, you must define the @make@ variable +@TOP@ to be the directory containing the @mk@ directory in which +the @boilerplate.mk@ file is. +It is {\em not} OK to simply say +\begin{verbatim} + include ../mk/boilerplate.mk # NO NO NO +\end{verbatim} +Why? Because the @boilerplate.mk@ file needs to know where it is, +so that it can, in turn, @include@ other files. +(Unfortunately, when an @include@d file does an +@include@, the filename is treated +relative to the directory in which @gmake@ is being run, not +the directory in which the @included@ sits.) +In general, +{\em every file @foo.mk@ +assumes that @$(TOP)/mk/foo.mk@ refers to itself.} +It is up to the @Makefile@ doing the @include@ to ensure this +is the case. + +Files intended for inclusion in other @Makefile@s are written to have +the following property: +{\em after @foo.mk@ is @include@d, it leaves @TOP@ containing the same +value as it had just before the @include@ statement}. +In our example, this invariant guarantees that the @include@ +for @target.mk@ will look in the same directory as that for +@boilerplate.mk@. + +\item The second section +defines the following standard @make@ variables: @SRCS@ (the source files from +which is to be built), and @HS_PROG@ (the +executable binary to be built). +We will discuss in more detail what the ``standard variables'' are, +and how they affect what happens, in Section~\ref{sect_targets}. + +The definition for @SRCS@ uses the useful GNU @make@ +construct @$(wildcard@~$pat$@)@, which expands to a list of all the +files matching the pattern $pat$ in the current directory. +In this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@ files +in the directory. (Let's suppose there is one of each, @Foo.lhs@ +and @Baz.c@.) + +\item The last section includes a second file of standard code, +called @target.mk@. It contains the rules that tell @gmake@ +how to make the standard targets +(Section~\ref{sect_standard-targets}). +Why, you ask, can't this standard code +be part of @boilerplate.mk@? Good question. +We discuss the reason later, in Section~\ref{sect_boiler-arch}. + +You do not {\em have} to @include@ the @target.mk@ file. Instead, +you can write rules of your own for all the standard targets. +Usually, though, you will find quite a big payoff from using +the canned rules in +@target.mk@; the price tag is that you have to understand +what canned rules get enabled, and what they do (Section~\ref{sect_targets}). +\end{enumerate} + +In our example @Makefile@, most of the work is done +by the two @include@d files. When you say @gmake all@, +the following things happen: +\begin{itemize} +\item @gmake@ figures out that the object files are @Foo.o@ and @Baz.o@. +\item It uses a boilerplate pattern rule to compile +@Foo.lhs@ to @Foo.o@ using +a Haskell compiler. (Which one? That is set in the build configuration.) +\item It uses another standard pattern rule to compile @Baz.c@ to @Baz.o@, +using a C compiler. (Ditto.) +\item It links the resulting @.o@ files together to make @small@, +using the Haskell compiler to do the link step. (Why not use @ld@? Because +the Haskell compiler knows what standard librarise to link in. How did @gmake@ +know to use the Haskell compiler to do the link, rather than the C compiler? +Because we set the variable @HS_PROG@ rather than @C_PROG@.) +\end{itemize} +All @Makefile@s should follow the above three-section format. + +\subsection{A larger project} + +Larger projects are usually structured into a nummber of sub-directories, +each of which has its own @Makefile@. (In very large projects, this +sub-structure might be iterated recursively, though that is rare.) +To give you the idea, here's part of the directory structure for +the (rather large) @ghc@ project: +\begin{verbatim} + $(FPTOOLS_TOP)/ghc/ + Makefile + + mk/ + boilerplate.mk + rules.mk + + docs/ + Makefile + ...source files for documentation... + + driver/ + Makefile + ...source files for driver... + + compiler/ + Makefile + parser/...source files for parser... + renamer/...source files for renamer... + ...etc... +\end{verbatim} +The sub-directories @docs@, @driver@, @compiler@, and so on, each contains +a sub-component of @ghc@, and each has its own @Makefile@. +There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@. +It does most of its work by recursively invoking @gmake@ +on the @Makefile@s in the sub-directories. +We say that @ghc/Makefile@ is a {\em non-leaf @Makefile@}, +because it does little except organise its children, while the @Makefile@s +in the sub-directories are all {\em leaf @Makefile@s}. (In principle +the sub-directories might themselves contain a non-leaf @Makefile@ and +several sub-sub-directories, but that does not happen in @ghc@.) + +The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even +though the @ghc/compiler@ has sub-directories, because these sub-directories +do not themselves have @Makefile@ in them. They are just used to structure +the collection of modules that make up @ghc@, but all are managed by the +single @Makefile@ in @ghc/compiler@. + +You will notice that @ghc/@ also contains a directory @ghc/mk/@. +It contains @ghc@-specific @Makefile@ boilerplate code. +More precisely: +\begin{itemize} +\item @ghc/mk/boilerplate.mk@ is included at the top of @ghc/Makefile@, +and of all the leaf @Makefile@s in the sub-directories. +It in turn @include@s the main boilerplate file @mk/boilerplate.mk@. + +\item @ghc/mk/target.mk@ is @include@d at the bottom of @ghc/Makefile@, +and of all the leaf @Makefiles@ in the sub-directories. +It in turn @include@s the file @mk/target.mk@. +\end{itemize} +So these two files are the place to look for @ghc@-wide customisation +of the standard boilerplate. + + + +\subsection{Boilerplate architecture} +\label{sect_boiler-arch} + +Every @Makefile@ includes a @boilerplate.mk@ file at the top, +and @target.mk@ file at the bottom. In this section we discuss +what is in these files, and why there have to be two of them. +In general: +\begin{itemize} +\item @boilerplate.mk@ consists of: +\begin{itemize} +\item {\em Definitions of millions of @make@ variables} that collectively +specify the build configuration. Examples: @HC_OPTS@, the options to +feed to the Haskell compiler; @NoFibSubDirs@, the sub-directories to +enable within the @nofib@ project; @GhcWithHc@, the name of the +Haskell compiler to use when compiling @GHC@ in the @ghc@ project. +\item {\em Standard pattern rules} that tell @gmake@ how to construct +one file from another. +\end{itemize} +@boilerplate.mk@ needs to be @include@d at the {\em top} of each +@Makefile@, so that the +user can replace the boilerplate definitions or pattern rules by simply +giving a new definition or pattern rule in the @Makefile@. @gmake@ simply +takes the last definition as the definitive one. + +Instead of {\em replacing} boilerplate definitions, it is also quite +common to {\em augment} them. For example, a @Makefile@ might say: +\begin{verbatim} + SRC_HC_OPTS += -O +\end{verbatim} +thereby adding ``@-O@'' to the end of @SRC_HC_OPTS@. + +\item @target.mk@ contains @make@ rules for the standard targets described +in Section~\ref{sect_standard-targets}. +These rules are selectively included, depending on the setting of +certain @make@ variables. These variables are usually set in the middle +section of the @Makefile@ between the two @include@s. + +@target.mk@ must be included at the end (rather than being part of @boilerplate.mk@) +for several tiresome reasons: +\begin{itemize} +\item @gmake@ commits target and dependency lists earlier than it should. +For example, @target.mk@ has a rule that looks like this: +\begin{verbatim} + $(HS_PROG) : $(OBJS) + $(HC) $(LD_OPTS) $< -o $@ +\end{verbatim} +If this rule was in @boilerplate.mk@ then @$(HS_PROG)@ and @$(OBJS)@ +would not have their final values at the moment @gmake@ encountered the +rule. Alas, @gmake@ takes a snapshot of their current values, and +wires that snapshot into the rule. +(In contrast, the commands executed when the rule ``fires'' are +only substituted at the moment of firing.) +So, the rule must follow the definitions given in the @Makefile@ itself. + +\item Unlike pattern rules, ordinary rules cannot be overriden or +replaced by subsequent rules for the same target (at least not without an +error message). Including ordinary rules in @boilerplate.mk@ would +prevent the user from writing rules for specific targets in specific cases. + +\item There are a couple of other reasons I've forgotten, but it doesn't +matter too much. +\end{itemize} +\end{itemize} + +\subsection{The main @mk/boilerplate.mk@ file} +\label{sect_boiler} + +If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find that +it consists of the following sections, each held in a separate file: +\begin{description} +\item[@config.mk@] is the build configuration file we discussed at length +in Section~\ref{sect_build-config}. + +\item[@paths.mk@] defines @make@ variables for pathnames and file +lists. In particular, it gives definitions for: +\begin{description} +\item[@SRCS@:] all source files in the current directory. +\item[@HS_SRCS@:] all Haskell source files in the current directory. +It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value +@HS_SRCS@ will follow suit. +\item[@C_SRCS@:] similarly for C source files. +\item[@HS_OBJS@:] the @.o@ files derived from @$(HS_SRCS)@. +\item[@C_OBJS@:] similarly for @$(C_SRCS)@. +\item[@OBJS@:] the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@. +\end{description} +Any or all of these definitions can easily be overriden by giving new +definitions in your @Makefile@. For example, +if there are things in the current directory that look like source files +but aren't, then you'll need to set @SRCS@ manually in your @Makefile@. +The other definitions will then work from this new definition. + +What, exactly, does @paths.mk@ consider a ``source file'' to be. +It's based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc), +but this is the kind of detail that changes +more rapidly, so rather than enumerate the source suffices here the best thing +to do is to look in @paths.mk@. + +\item[@opts.mk@] defines @make@ variables for option strings to +pass to each program. For example, it defines @HC_OPTS@, the +option strings to pass to the Haskell compiler. See \sectionref{sect_suffix}. + +\item[@suffix.mk@] defines standard pattern rules -- see \sectionref{sect_suffix} +\end{description} +Any of the variables and pattern rules defined by the boilerplate file +can easily be overridden in any particular @Makefile@, because +the boilerplace @include@ comes first. Definitions after this +@include@ directive simply override the default ones in @boilerplate.mk@. + +\subsection[sect_suffix]{Pattern rules and options} + +The file @suffix.mk@ defines standard {\em pattern rules} that say how to build one kind +of file from another, for example, how to build a @.o@ file from a @.c@ file. +(GNU @make@'s {\em pattern rules} are more powerful and easier to use than +Unix @make@'s {\em suffix rules}.) + +Almost all the rules look something like this: +\begin{verbatim} +%.o : %.c + @$(RM) $@ + $(CC) $(CC_OPTS) -c $< -o $@ +\end{verbatim} +Here's how to understand the rule. It says that $something@.o@$ (say @Foo.o@) +can be built from $something@.c@$ (@Foo.c@), by invoking the C compiler +(path name held in @$(CC)@), passing to it the options @$(CC_OPTS)@ and the rule's +dependent +file of the rule @$<@ (@Foo.c@ in this case), and putting the result in +the rule's target @$@@@ (@Foo.o@ in this case). + +Every program is held in a @make@ variable defined in @mk/config.mk@ --- look in @mk/config.mk@ for +the complete list. One important one is the Haskell compiler, which is called @$(HC)@. + +Every programs options are are held in a @make@ variables called @<prog>_OPTS@. +the @<prog>_OPTS@ variables are defined in @mk/opts.mk@. Almost all of them are defined +like this: +\begin{verbatim} + CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) +\end{verbatim} +The four variables from which @CC_OPTS@ is built have the following meaning: +\begin{description} +\item[@SRC_CC_OPTS@:] options passed to all C compilations. +\item[@WAY_<way>_CC_OPTS@:] options passed to C compilations for way @<way>@. For example, +@WAY_mp_CC_OPTS@ gives options to pass to the C compiler when compiling way @mp@. +The variable @WAY_CC_OPTS@ holds options to pass to the C compiler when compiling the standard way. +(Section~\ref{sect_ways} dicusses multi-way compilation.) +\item[@<module>_CC_OPTS@:] options to pass to the C compiler that are specific to module @<module>@. +For example, @SMap_CC_OPTS@ gives the specific options to pass to the C compiler when compiling +@SMap.c@. +\item[@EXTRA_CC_OPTS@:] extra options to pass to all C compilations. This is intended for command +line use, thus; +\begin{verbatim} + gmake libHS.a EXTRA_CC_OPTS="-v" +\end{verbatim} +\end{description} + + +\subsection{The main @mk/target.mk@ file} +\label{sect_targets} + +@target.mk@ contains canned rules for all the standard targets described in +Section~\ref{sect_standard-targets}. It is complicated by the fact +that you don't want all of these rules to be active in every @Makefile@. +Rather than have a plethora of tiny files which you can include selectively, +there is a single file, @target.mk@, which selectively includes rules +based on whether you have defined certain variables in your @Makefile@. +This section explains what rules you get, what variables control them, and +what the rules do. Hopefully, you will also get enough of an idea of what is supposed +to happen that you can read and understand any wierd special cases yourself. + +\begin{description} +\item{@HS_PROG@.} If @HS_PROG@ is defined, you get rules with the +following targets: +\begin{description} +\item[@HS_PROG@] itself. This rule links @$(OBJS)@ with the Haskell +runtime system to get an executable called @$(HS_PROG)@. +\item[@install@] installs @$(HS_PROG)@ in @$(bindir)@ with the execute bit set. +\end{description} + +\item[@C_PROG@] is similar to @HS_PROG@, except that the link step +links @$(C_OBJS)@ with the C runtime system. + +\item[@LIBRARY@] is similar to @HS_PROG@, except +that it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@, +and @install@ installs it in @$(libdir)@, with the execute bit not set. + +\item[@LIB_DATA@] ... +\item[@LIB_EXEC@] ... + +\item[@HS_SRCS@, @C_SRCS@.] If @HS_SRCS@ is defined and non-empty, a rule for +the target @depend@ is included, which generates dependency information for +Haskell programs. Similarly for @C_SRCS@. +\end{description} + +All of these rules are ``double-colon'' rules, thus +\begin{verbatim} + install :: $(HS_PROG) + ...how to install it... +\end{verbatim} +GNU @make@ treats double-colon rules as separate entities. If there +are several double-colon rules for the same target it takes each in turn +and fires it if its dependencies say to do so. This means that you can, +for example, define both @HS_PROG@ and @LIBRARY@, which will generate two +rules for @install@. When you type @gmake install@ both rules will be fired, +and both the program and the library will be installed, just as you wanted. + +\subsection{Recursion} +\label{sect_subdirs} + +In leaf @Makefiles@ the variable @SUBDIRS@ is undefined. In non-leaf +@Makefiles@, @SUBDIRS@ is set to the list of sub-directories that contain subordinate +@Makefile@s. {\em It is up to you to set @SUBDIRS@ in the @Makefile@.} +There is no automation here --- @SUBDIRS@ is too important automate. + +When @SUBDIRS@ is defined, @target.mk@ includes a rather neat rule for +the standard targets (Section~\ref{sect_standard-targets}) that +simply invokes @make@ recursively in each of the sub-directories. + +{\em These recursive invocations are guaranteed to occur in the order in +which the list of directories is specified in @SUBDIRS@.} This guarantee can +be important. For example, when you say @gmake boot@ it can be important +that the recursive invocation of @make boot@ is done in one sub-directory (the include +files, say) before another (the source files). +Generally, put the most independent sub-directory first, and the most dependent +last. + +\subsection{Way management} +\label{sect_ways} + +We sometimes want to build essentially the same system in several different +``ways''. For example, we want to build @ghc@'s @Prelude@ libraries with +and without profiling, with and without concurrency, and so on, so that +there is an appropriately-built library archive to link with when the user compiles +his program. +It would be possible to have a completely separate build tree for each such ``way'', +but it would be horribly bureaucratic, especially since often only parts of the +build tree need to be constructed in multiple ways. + +Instead, the @template.mk@ contains some clever magic to allow you to build +several versions of a system; and to control locally how many versions are built +and how they differ. This section explains the magic. + +The files for a particular way are distinguished by munging the suffix. +The ``normal way'' is always built, and its files have the standard suffices +@.o@, @.hi@, and so on. In addition, you can build one or more extra ways, +each distinguished by a {\em way tag}. The object files and interface files +for one of these extra ways are distinguished by their suffix. For example, +way @mp@ has files @.mp_o@ and @.mp_hi@. Library archives have their way +tag the other side of the dot, for boring reasons; thus, @libHS_mp.a@. + +A @make@ variable called @way@ holds the current way tag. {\em @way@ is only ever +set on the command line of a recursive invocation of @gmake@.} It is +never set inside a @Makefile@. So it is a global constant for any one invocation +of @gmake@. Two other @make@ variables, @way_@ and @_way@ are immediately derived +from @$(way)@ and never altered. If @way@ is not set, then neither are @way_@ +and @_way@, and the invocation of @make@ will build the ``normal way''. +If @way@ is set, then the other two variables are set in sympathy. +For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@'' +and @_way@ is set to ``@_mp@''. These three variables are then used +when constructing file names. + +So how does @make@ ever get recursively invoked with @way@ set? There +are two ways in which this happens: +\begin{itemize} +\item For some (but not all) of the standard targets, when in a leaf sub-directory, +@make@ is recursively invoked for each way tag in @$(WAYS)@. You set @WAYS@ to +the list of way tags you want these targets built for. The mechanism here is +very much like the recursive invocation of @make@ in sub-directories +(Section~\ref{sect_subdirs}). + +It is up to you to set @WAYS@ in your @Makefile@; this is how you control +what ways will get built. +\item For a useful collection of targets (such as @libHS_mp.a@, @Foo.mp_o@) +there is a rule which recursively invokes @make@ to make the specified +target, setting the @way@ variable. So if you say @gmake Foo.mp_o@ +you should see a recursive invocation @gmake Foo.mp_o way=mp@, +and {\em in this recursive invocation the pattern rule for compiling a Haskell +file into a @.o@ file will match}. The key pattern rules (in @suffix.mk@) +look like this: +\begin{verbatim} + %.$(way_)o : %.lhs + $(HC) $(HC_OPTS) $< -o $@ +\end{verbatim} +Neat, eh? +\end{itemize} + + +\subsection{When the canned rule isn't right} + +Sometimes the canned rule just doesn't do the right thing. For example, in +the @nofib@ suite we want the link step to print out timing information. +The thing to do here is {\em not} to define @HS_PROG@ or @C_PROG@, and instead +define a special purpose rule in your own @Makefile@. +By using different variable names you will avoid the canned rules being included, +and conflicting with yours. + + +%************************************************************************ +%* * +\section[booting-from-C]{Booting/porting from C (\tr{.hc}) files} +\index{building GHC from .hc files} +\index{booting GHC from .hc files} +%* * +%************************************************************************ + +This section is for people trying to get GHC going by using the +supplied intermediate C (\tr{.hc}) files. This would probably be +because no binaries have been provided, or because the machine +is not ``fully supported.'' + +THIS SECTION HASN'T BEEN UPDATED YET. Please let us know if you want to use this +route. Unless someone does, this section may never get written, and the +.hc files distribution may not get built! + + +%************************************************************************ +%* * +\section[build-pitfalls]{Known pitfalls in building Glasgow Haskell} +\index{problems, building} +\index{pitfalls, in building} +\index{building pitfalls} +%* * +%************************************************************************ + +WARNINGS about pitfalls and known ``problems'': + +\begin{enumerate} +%------------------------------------------------------------------------ +\item +One difficulty that comes up from time to time is running out of space +in \tr{/tmp}. (It is impossible for the configuration stuff to +compensate for the vagaries of different sysadmin approaches re temp +space.) + +The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or +even \tr{setenv TMPDIR .} (or the equivalent incantation with the +shell of your choice). + +The best way around it is to say +\begin{verbatim} + TMPDIR=<dir> +\end{verbatim} +in your @build.mk@ file. +Then GHC and the other @fptools@ programs will use the appropriate directory +in all cases. + +%------------------------------------------------------------------------ +\item +In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and +even in \tr{ghc/lib}, you may get a few C-compiler warnings. We think +these are OK. + +%------------------------------------------------------------------------ +\item +When compiling via C, you'll sometimes get ``warning: +assignment from incompatible pointer type'' out of GCC. Harmless. + +%------------------------------------------------------------------------ +\item +Similarly, \tr{ar}chiving warning messages like the following are not +a problem: +\begin{verbatim} +ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ +ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ +... +\end{verbatim} + +%------------------------------------------------------------------------ +\item +Also harmless are some specialisation messages that you may see when +compiling GHC; e.g.: +\begin{verbatim} +SPECIALISATION MESSAGES (Desirable): +*** INSTANCES +{-# SPECIALIZE instance Eq [Class] #-} +{-# SPECIALIZE instance Eq (Class, [Class]) #-} +{-# SPECIALIZE instance Outputable [ClassOp] #-} +{-# SPECIALIZE instance Outputable [Id] #-} +\end{verbatim} + +%------------------------------------------------------------------------ +\item +In compiling the compiler proper (in \tr{compiler/}), you {\em may} get an +``Out of heap space'' error message. These +can vary with the vagaries of different systems, it seems. The +solution is simple: (1)~add a suitable \tr{-H} flag to the @<module>_HC_OPTS@ +@make@ variable in the appropriate @Makefile@; +(2)~try again: \tr{gmake}. +(Section~\ref{sect_suffix}.) + +Alternatively, just cut to the chase scene: +\begin{verbatim} +% cd ghc/compiler +% make EXTRA_HC_OPTS=-H32m # or some nice big number +\end{verbatim} + +%------------------------------------------------------------------------ +\item +Not too long into the build process, you may get a huge complaint +of the form: +\begin{verbatim} +Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27. +\end{verbatim} +This indicates that your \tr{perl} was mis-installed; the binary is +unable to find the files for its ``built-in'' library. Speak to your +perl installer, then re-try. + +%------------------------------------------------------------------------ +\item +If you try to compile some Haskell, and you get errors from GCC +about lots of things from \tr{/usr/include/math.h}, then your GCC +was mis-installed. \tr{fixincludes} wasn't run when it should've +been. + +As \tr{fixincludes} is now automagically run as part of GCC +installation, this bug also suggests that you have an old GCC. + + +%------------------------------------------------------------------------ +\item +You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s). +\begin{verbatim} +% cd $(libdir)/ghc-2.01/sparc-sun-sunos4 +% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... +? ranlib $i +? # or, on some machines: ar s $i +? end +\end{verbatim} +We'd be interested to know if this is still necessary. + +%------------------------------------------------------------------------ +\item +If you end up making documents that involve (La)TeX and/or \tr{tib} +(Simon's favourite), the odds are that something about your/our setup +will reach out and bite you. Yes, please complain; meanwhile, +you can do \tr{make -n whatever.dvi} to see the intended commands, +then try to muddle through, doing them by hand. + +\end{enumerate} + + + +% ==================================================================== +Here follow pitfalls that apply to pre-2.02 releases. They should not +happen any more If they do crop up with 2.02 or later, please let us +know. + +\begin{enumerate} +%------------------------------------------------------------------------ +\item +When configuring the support code (mkworld, glafp-utils, etc.), you +will see mention of \tr{NO_SPECIFIC_PROJECT} and +\tr{NO_SPECIFIC_VERSION}. This is cool. + + +%------------------------------------------------------------------------ +\item +Sooner or later in your ``make-worlding'' life you will do and see +something like: +\begin{verbatim} +% make Makefile + rm -f Makefile.bak; mv Makefile Makefile.bak +../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=... +../.././mkworld/jrestoredeps +==== The new Makefile is for: ==== +make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen +Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard +*** Error code 1 +make: Fatal error: Command failed for target `Makefile' +\end{verbatim} + +Don't panic! It should restore your previous \tr{Makefile}, and +leave the junk one in \tr{Makefile.bad}. Snoop around at your leisure. + +% ------------------------------------------------------------------------ +\item +If you do corrupt a \tr{Makefile} totally, or you need to glue a new +directory into the directory structure (in \tr{newdir}---which must +have a \tr{Jmakefile}, even if empty), here's a neat trick: +\begin{verbatim} +# +# move to the directory just above the one where you want a Makefile... +cd .. +# +# make Makefiles, but lie about the directories below... +make Makefiles SUBDIRS=newdir +\end{verbatim} + +This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and +it will be properly wired into the general make-world structure. + +% ------------------------------------------------------------------------ +\item +Don't configure/build/install using a variety of machines. A +mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to +build GHC (\tr{make all}) on a Sun3. + +%------------------------------------------------------------------------ +%\item +%If you build an ``unregisterised'' build, you will get bazillions of +%warnings about `ANSI C forbids braced-groups within expressions'. +%Especially in \tr{ghc/lib}. These are OK. + +\end{enumerate} + + +\begin{onlystandalone} +\printindex +\end{document} +\end{onlystandalone} + |