From: simonm Date: Tue, 13 Jan 1998 12:14:44 +0000 (+0000) Subject: [project @ 1998-01-13 12:14:40 by simonm] X-Git-Tag: Approx_2487_patches~1097 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=fbf2e16821d9661d4a086ddb4eaaf31b97f17740 [project @ 1998-01-13 12:14:40 by simonm] SGML version of the installation guide. SGML-Tools 1.0.3 or later is required, and the indexing still doesn't work automatically. --- diff --git a/docs/Makefile b/docs/Makefile index b2164c4..203cf3c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,7 +1,9 @@ TOP = .. include $(TOP)/mk/boilerplate.mk -DOC_SRCS = installing.lit +DOC_SRCS = installing.vsgml + +CLEAN_FILES += installing.sgml installing*.html installing.info* SRC_TEXI2HTML_OPTS += -number -monolithic -invisible xbm diff --git a/docs/installing.lit b/docs/installing.lit deleted file mode 100644 index 73713a7..0000000 --- a/docs/installing.lit +++ /dev/null @@ -1,1785 +0,0 @@ -% Building and installing the Glasgow Functional Programming Tools Suite -% -% Version 3.00 -% July 1997 - - -\begin{onlystandalone} -\documentstyle[11pt,literate]{article} -\begin{document} -\title{Building and installing the Glasgow Functional Programming Tools Suite\\ -Version~3.00} -\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 was 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 read earlier versions. - -\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. Section~\ref{installing-bin-distrib} describes -how to do this. - -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 haven'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 find 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. - -We make source distributions more frequently than binary -distributions; a release that comes with pre-compiled binaries -is considered a major release, i.e., a release that we have some -confidence will work well by having tested it (more) thoroughly. - -Source-only distributions are either bugfix releases or snapshots of -current state of development. The release has undergone some testing. -Source releases of 2.0x can be compiled up using 2.07 (or subsequent -bugfix releases) or the Good Old Compiler, GHC~0.29. Compiling with -0.29 is recommended if you're a performance junkie, as 0.29 (still) -generates zippier code, but GHC~2.0x is catching up. - -\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}. - -Once you have built GHC, you can build the other Glasgow tools with -it. - -In theory, you can (could?) build GHC with another Haskell compiler -(e.g., HBC). We haven't tried to do this for ages and it almost -certainly doesn't work any more (for tedious reasons). - -\item[The CVS repository.] - -We make source distributions slightly more often than binary -distributions; but still infrequently. 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. - - -All of the above are {\em estimates} of disk-space needs.(I don't yet -know the disk requirements for the non-GHC tools). - -\item -Use an appropriate machine, compilers, and things. - -SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD, -or Solaris are all fully supported. MIPS, AIX, Win32 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}). Also check the ``known bugs'' web page -for GHC: - -\begin{center} -@http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html@ -\end{center} - -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 @glasgow-haskell-bugs@@dcs.gla.ac.uk@. -\end{enumerate} - - -%************************************************************************ -%* * -\section[port-info]{What machines the Glasgow tools 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@. Other common ones are -@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@, -@i386-unknown-solaris2@, @i386-unknown-freebsd@, -@i386-unknown-cygwin32@, @m68k-sun-sunos4@, @mips-sgi-irix5@, -@sparc-sun-sunos4@, @sparc-sun-solaris2@, @powerpc-ibm-aix@. - -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. We identify platforms -by their ``canonical'' CPU/Manufacturer/OS triple. - -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 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-*-freebsd} (PCs running FreeBSD 2.2 or higher, and -NetBSD/OpenBSD using FreeBSD emulation):] -\index{i386-*-freebsd:registerised port} -GHC 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 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{mips-sgi-irix6}:] -\index{mips-sgi-irix6: registerised port} -Thanks to the fine efforts of Tomasz Cholewo -\tr{}, GHC works registerised -(no native code generator) under IRIX 6.2 and 6.3. Depends on having -specially tweaked version of gcc-2.7.2 around, which can be downloaded -from - -\begin{verbatim} - http://mecca.spd.louisville.edu/~tjchol01/software/ -\end{verbatim} - -Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested). -\index{mips-sgi-irix6: concurrent---maybe} -\index{mips-sgi-irix6: parallel---maybe} -\index{mips-sgi-irix6: profiling---yes} - -%------------------------------------------------------------------- -\item[\tr{powerpc-ibm-aix}:] -\index{powerpc-ibm-aix: registerised port} -GHC works registerised (no native-code generator..yet). -I suspect 2.7.x is what you need together with this. - -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.29. -There's probably a little bit-rot since then, but otherwise it should -still be fine. - -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.0x 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{-.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-x.xx-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@] The announcement message for the bundle. -\item[@NEWS@] release notes for the bundle -- a longer version of -@ANNOUNCE@. For GHC, the release notes are contained in the User -Guide and this file isn't present. -\item[@bin/@] 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/@] 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 -there would be a sub-directory @ghc-x.xx/@ where @x.xx@ is the version -number of GHC in the bundle. - -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-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - - % gunzip < happy-x.xx-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-@ and @NEWS-@ 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@ -and typing @./configure@. 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 in-place@ to set the -tools up for this (where @make@ is GNU make - you might have to type -@gmake@ to get it). You'll also want to add the path which @make@ will -now echo to your @PATH@ environment variable. This option is useful if -you simply want to try out the package and/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} work 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 GHC as @ghc-x.xx@ where @x.xx@ is the version -number of GHC. It will also make a link (in the binary installation -directory) from @ghc@ to @ghc-x.xx@. 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-x.xx@ should always invoke GHC version @x.xx@. - -\subsection{What bundles there are} - -There are plenty of ``non-basic'' GHC bundles. The files for them are -called \tr{ghc-x.xx--.tar.gz}, where the -\tr{} is as above, and \tr{} 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-x.xx/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 should be Perl~4 friendly though. -For Win32 platforms, Perl~5 is recommended, we even strongly suggest -you pick up a port of Perl~5 for \tr{cygwin32}, as the common -Hip/ActiveWare port of Perl is not Cool Enough for our purposes. - -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. - -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. -On our machines, the version in @/bin@ doesn't work; you need the -GNU version. Find out by saying @flex --version@ (our current version -is 2.5.3, but maybe earlier ones will work). If it doesn't know about -the @--version@ flag, it ain't the right @flex@. - -\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 utilities which aren't -particularly Glasgow-ish, but Occasionally Indispensable. Like -@lndir@ for creating symbolic link trees. - -\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]{Building from source} -\index{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} -\label{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@, @config.sub@, @config.guess@: -these files support the configuration process. -\item @install-sh@. -\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 suite, -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 -a 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 (If you don't have either, the source -distribution includes sources for the \tr{X11} \tr{lndir} --- check -out \tr{fptools/glafp-utils/lndir} ). - -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! - -Remember, that the source files in the build tree are {\em symbolic -links} to the files in the source tree. (The build tree soon -accumulates lots of built files like @Foo.o@, as well.) You can {\em -delete} a source file from the build tree without affecting the source -tree (though it's an odd thing to do). On the other hand, if you {\em -edit} a source file from the build tree, you'll edit the source-tree -file directly. (You can set up Emacs so that if you edit a source -file from the build tree, Emacs will silently create an edited copy of -the source file in the build tree, leaving the source file unchanged; -but the danger is that you think you've edited the source file whereas -actually all you've done is edit the build-tree copy. More commonly -you do want to edit the source file.) - -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 three-step process. -\begin{description} - -\item[Step 1: get ready for configuration.] Change directory to -@$(FPTOOLS)@ and issue the command @autoconf@ (with no -arguments). This GNU program converts @$(FPTOOLS)/configure.in@ to a -shell script called @$(FPTOOLS)/configure@. - -Both these steps are completely platform-independent; they just mean -that the human-written file (@configure.in@) can be short, although -the resulting shell script, @configure@, and @mk/config.h.in@, are -long. - -In case you don't have @autoconf@ we distribute the results, -@configure@, and @mk/config.h.in@, with the source distribution. They -aren't kept in the repository, though. - -\item[Step 2: system configuration.] -Runs the newly-created @configure@ script, thus: -\begin{verbatim} - ./configure -\end{verbatim} -@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} -@configure@ caches the results of its run in @config.cache@. -Quite often you don't want that; you're running @configure@ a second time -because something has changed. In that case, simply delete @config.cache@. - -\item[Step 3: 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} - ProjectsToBuild = glafp-utils literate happy ghc hslibs -\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 @green-card@, you can add this line to @build.mk@: -\begin{verbatim} - ProjectsToBuild += green-card -\end{verbatim} -or, if you prefer, -\begin{verbatim} - ProjectsToBuild = glafp-utils literate happy ghc hslibs green-card -\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@. - -You can also use @build.mk@ to override anything that @configure@ got -wrong. One place where this happens often is with the definition of -@FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path -to the top of your source tree, but if your system uses an automounter -then the correct directory is hard to find automatically. If you find -that @configure@ has got it wrong, just put the correct definition in -@build.mk@. - -\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@). -Make sure that you have the essential files (see Section~\ref{source-tree}). - -\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 Prepare for system configuration: -\begin{verbatim} - autoconf -\end{verbatim} -(You can skip this step if you are starting from a source distribution, -and you already have @configure@ and @mk/config.h.in@.) - -\item Do system configuration: -\begin{verbatim} - ./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, -but note that this is a one-off, i.e., there's no need to re-do -@gmake boot@ if you should re-configure your build tree at a later -stage (no harm caused if you do though). - -\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 @_OPTS@. -the @_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__CC_OPTS@:] options passed to C compilations for 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[@_CC_OPTS@:] options to pass to the C compiler that are specific to 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.'' - -The intermediate C files are normally made available together with a -source release, please check the announce message for exact directions -of where to find them. If we've haven't made them available or you -can't find them, please ask. - -Assuming you've got them, unpack them on top of a fresh source tree. -Then follow the `normal' instructions in -\sectionref{building-from-source} for setting up a build tree and -configuring it. The only extra thing to remember when booting from -\tr{.hc} files is to add the following line to the \tr{build.mk} -file: - -\begin{verbatim} -GhcWithHscBuiltViaC=YES -\end{verbatim} - -and proceed with doing a \tr{make boot} followed by a \tr{make all}. - -That's the mechanics of the boot process, but, of course, if you're -trying to boot on a platform that is not supported and significantly -`different' from any of the supported ones, this is only the start -of the adventure...(ToDo: porting tips - stuff to look out for, etc.) - - -%************************************************************************ -%* * -\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} -export TMPDIR= -\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 @_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-x.xx/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. - -%------------------------------------------------------------------------ -\item -GHC's sources go through \tr{cpp} -before being compiled, and \tr{cpp} varies a bit from one Unix to another. -One particular gotcha is macro calls like this: -\begin{verbatim} - SLIT("Hello, world") -\end{verbatim} -Some \tr{cpp}s treat the comma inside the string as separating two macro arguments, -so you get -\begin{verbatim} - :731: macro `SLIT' used with too many (2) args -\end{verbatim} -Alas, \tr{cpp} doesn't tell you the offending file! - -Workaround: don't put wierd things in string args to \tr{cpp} macros. -\end{enumerate} - -\begin{onlystandalone} -\printindex -\end{document} -\end{onlystandalone} - diff --git a/docs/installing.vsgml b/docs/installing.vsgml new file mode 100644 index 0000000..ac68402 --- /dev/null +++ b/docs/installing.vsgml @@ -0,0 +1,1945 @@ + +
+ +Building and Installing the Glasgow Functional Programming Tools Suite +Version 3.00 +<author>The GHC Team, +Department of Computing Science, +University of Glasgow, +Glasgow, Scotland, +G12 8QQ. + +Email: @glasgow-haskell-{users,bugs}@@dcs.gla.ac.uk@ +<date>November 1997</date> + +<abstract> + +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 was 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 read earlier versions. +</abstract> + +<toc> + +<sect>Getting the Glasgow @fptools@ suite +<label id="sec:getting"> +<p> + +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: + +<descrip> + +<tag><idx>Binary distribution</idx>.</tag> + 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. Section +<ref id="sec:installing-bin-distrib" name="Installing a Binary +Distribution"> describes how to do this. + +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 haven'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. + +<tag><idx>Source distribution</idx>.</tag> 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@<ncdx/flex/ +you'll find 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. + +We make source distributions more frequently than binary +distributions; a release that comes with pre-compiled binaries +is considered a major release, i.e., a release that we have some +confidence will work well by having tested it (more) thoroughly. + +Source-only distributions are either bugfix releases or snapshots of +current state of development. The release has undergone some testing. +Source releases of 2.0x can be compiled up using 2.07 (or subsequent +bugfix releases) or the Good Old Compiler, GHC~0.29. Compiling with +0.29 is recommended if you're a performance junkie, as 0.29 (still) +generates zippier code, but GHC~2.0x is catching up. + +<tag/Build GHC from intermediate C @.hc@ files<nidx/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 (@.hc@) files that we provide. Building GHC +on an unsupported platform falls into this category. Please see +Section <ref id="sec:booting-from-C" name="Booting From C">. + +Once you have built GHC, you can build the other Glasgow tools with +it. + +In theory, you can (could?) build GHC with another Haskell compiler +(e.g., HBC). We haven't tried to do this for ages and it almost +certainly doesn't work any more (for tedious reasons). + +<tag/The CVS repository./ + +We make source distributions slightly more often than binary +distributions; but still infrequently. 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! +</descrip> + +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. + +<sect>Things to check before you start typing +<p> + +Here's a list of things to check before you get started. +<enum> +<item> +<idx>Disk space needed</idx>: 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. + + +All of the above are <em/estimates/ of disk-space needs.(I don't yet +know the disk requirements for the non-GHC tools). + +<item> +Use an appropriate machine, compilers, and things. + +SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD, +or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are +in pretty good shape. Section <ref id="sec:port-info" name="Port Info"> +gives the full run-down on ports or lack thereof. + +<item> Be sure that the ``pre-supposed'' utilities are installed. +Section <ref id="sec:pre-supposed" name="Installing Pre-Supposed +Utilities"> elaborates. + +<item> If you have any problem when building or installing the Glasgow +tools, please check the ``known pitfalls'' (Section <ref +id="sec:build-pitfalls" name="Building Pitfalls">). Also check the +known bugs page: <url +url="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html">. +<nidx/known bugs/ +<nidx/bugs, known/ + +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. +<nidx/bugs, reporting/ + +If in doubt, please send a message to @glasgow-haskell-bugs@@dcs.gla.ac.uk@. +<nidx/bugs, mailing list/ +</enum> + + +<sect>What machines the Glasgow tools run on +<label id="sec:port-info"> +<p> +<nidx>ports, GHC</nidx> +<nidx>GHC ports</nidx> +<nidx>supported platforms</nidx> +<nidx>platforms, supported</nidx> + +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@. Other common ones are +@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@, +@i386-unknown-solaris2@, @i386-unknown-freebsd@, +@i386-unknown-cygwin32@, @m68k-sun-sunos4@, @mips-sgi-irix5@, +@sparc-sun-sunos4@, @sparc-sun-solaris2@, @powerpc-ibm-aix@. + +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. + +<sect1>What platforms the Haskell compiler (GHC) runs on +<p> +<nidx>fully-supported platforms</nidx> +<nidx>native-code generator</nidx> +<nidx>registerised ports</nidx> +<nidx>unregisterised ports</nidx> + +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 Sparcs running Solaris 2.5, x86 boxes running FreeBSD and +Linux, and DEC~Alphas running OSF/1~V2.0, so those are the +``fully-supported'' platforms, unsurprisingly. All 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. We identify platforms +by their ``canonical'' CPU/Manufacturer/OS triple. + +Note that some ports are fussy about which GCC version you use; or +require GAS; or ... + +<descrip> +<tag/alpha-dec-osf1:/ +<nidx>alpha-dec-osf1: fully supported</nidx> + +(We have OSF/1 V3.0.) Fully supported, including native-code +generator. We recommend GCC 2.6.x or later. + +<tag/sparc-sun-sunos4:/ +<nidx>sparc-sun-sunos4: fully supported</nidx> + +Fully supported, including native-code generator. + +<tag/sparc-sun-solaris2:/ +<nidx>sparc-sun-solaris2: fully supported</nidx> + +Fully supported, including native-code generator. A couple of quirks, +though: (a)~the profiling libraries are bizarrely huge when compiled +with object splitting; (b)~the default @xargs@<ncdx/xargs/ program is +atrociously bad for building GHC libraries (see Section <ref +id="sec:pre-supposed" name="Installing Pre-Supposed Utilities"> for +details). + +<tag/HP-PA box running HP/UX 9.x:/ +<nidx>hppa1.1-hp-hpux: registerised port</nidx> + +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 +@jaguar.cs.utah.edu@. We think a straight GCC 2.7.x works, +too. + +Concurrent/Parallel Haskell probably don't work (yet). +<nidx>hppa1.1-hp-hpux: concurrent---no</nidx> +<nidx>hppa1.1-hp-hpux: parallel---no</nidx> + +<tag/i386-*-linux (PCs running Linux---ELF format):/ +<nidx>i386-*-linux: registerised port</nidx> + +GHC 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. +<nidx>i386-*-linux: profiling---yes</nidx> +<nidx>i386-*-linux: concurrent---yes</nidx> +Parallel Haskell probably works. +<nidx>i386-*-linux: parallel---maybe</nidx> + +On old Linux a.out systems: should be the same. +<nidx>i386-*-linuxaout: registerised port</nidx> + +<tag>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and +NetBSD/OpenBSD using FreeBSD emulation):</tag> +<nidx>i386-*-freebsd:registerised port</nidx> + +GHC works registerised. Supports same set of bundles as the above. + +<nidx>i386-*-freebsd: profiling---yes</nidx> +<nidx>i386-*-freebsd: concurrent---yes</nidx> +<nidx>i386-*-freebsd: parallel---maybe</nidx> + +<tag/i386-unknown-cygwin32:/ +<nidx>i386-unknown-cygwin32: fully supported</nidx> + +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. + +<nidx>i386-*-cygwin32: profiling---yes</nidx> +<nidx>i386-*-cygwin32: concurrent---yes</nidx> + +<tag/mips-sgi-irix5:/ +<nidx>mips-sgi-irix5: registerised port</nidx> + +GHC 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 +@--with-gnu-as@; turns out that is important! + +Concurrent/Parallel Haskell probably don't work (yet). +Profiling might work, but it is untested. +<nidx>mips-sgi-irix5: concurrent---no</nidx> +<nidx>mips-sgi-irix5: parallel---no</nidx> +<nidx>mips-sgi-irix5: profiling---maybe</nidx> + +<tag/mips-sgi-irix6:/ +<nidx>mips-sgi-irix6: registerised port</nidx> + +Thanks to the fine efforts of Tomasz Cholewo <htmlurl +url="mailto:tjchol01@@mecca.spd.louisville.edu" +name="<tjchol01@@mecca.spd.louisville.edu>">, GHC works registerised +(no native code generator) under IRIX 6.2 and 6.3. Depends on having +specially tweaked version of gcc-2.7.2 around, which can be downloaded +from <url url="http://mecca.spd.louisville.edu/~tjchol01/software/">. + +Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested). +<nidx>mips-sgi-irix6: concurrent---maybe</nidx> +<nidx>mips-sgi-irix6: parallel---maybe</nidx> +<nidx>mips-sgi-irix6: profiling---yes</nidx> + +<tag/powerpc-ibm-aix:/ +<nidx>powerpc-ibm-aix: registerised port</nidx> +GHC works registerised (no native-code generator..yet). +I suspect 2.7.x is what you need together with this. + +Concurrent/Parallel Haskell probably don't work (yet). +Profiling might work, but it is untested. +<nidx>mips-sgi-irix5: concurrent---no</nidx> +<nidx>mips-sgi-irix5: parallel---no</nidx> +<nidx>mips-sgi-irix5: profiling---maybe</nidx> + +<tag/m68k-apple-macos7 (Mac, using MPW):/ +<nidx>m68k-apple-macos7: historically ported</nidx> +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. + +<tag/m68k-next-nextstep3:/ +<nidx>m68k-next-nextstep3: historically ported</nidx> +Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29. +There's probably a little bit-rot since then, but otherwise it should +still be fine. + +Concurrent/Parallel Haskell probably won't work (yet). +<nidx>m68k-next-nextstep3: concurrent---no</nidx> +<nidx>m68k-next-nextstep3: parallel---no</nidx> + +<tag/m68k-sun-sunos4 (Sun3):/ +<nidx>m68k-sun-sunos4: registerised port</nidx> +GHC 2.0x hasn't been tried on a Sun3. GHC~0.26 worked registerised. +No native-code generator. + +Concurrent/Parallel Haskell probably don't work (yet). +<nidx>m68k-sun-sunos4: concurrent---no</nidx> +<nidx>m68k-sun-sunos4: parallel---no</nidx> +</descrip> + +<sect1>What machines the other tools run on +<p> + +Unless you hear otherwise, the other tools work if GHC works. + +Haggis requires Concurrent Haskell to work. +<nidx>Haggis, Concurrent Haskell</nidx> + + +<sect>Installing from binary distributions +<p> +<label id="sec:installing-bin-distrib"> +<nidx>binary installations</nidx> +<nidx>installation, of binaries</nidx> + +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.) + + +<sect1>Bundle structure<p> +<nidx>bundles of binary stuff</nidx> + +Binary distributions come in ``bundles,'' one bundle per file called +@<bundle>-<platform>.tar.gz@. (See Section <ref +id="sec:port-info" name="Porting Information"> for what a platform +is.) Suppose that you untar a binary-distribution bundle, thus: + +<tscreen><verb> + % cd /your/scratch/space + % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - +</verb></tscreen> + +Then you should find a single directory, @fptools@, with the following +structure: + +<nidx>binary distribution, layout</nidx> +<nidx>directory layout (binary distributions)</nidx> +<descrip> + +<tag>@Makefile.in@</tag> the raw material from which the @Makefile@ +will be made (Section <ref id="sec:install" name="Installation">). + +<tag>@configure@</tag> the configuration script (Section <ref +id="sec:install" name="Installing">). + +<tag>@README@</tag> Contains this file summary. + +<tag>@INSTALL@</tag> Contains this description of how to install +the bundle. + +<tag>@ANNOUNCE@</tag> The announcement message for the bundle. + +<tag>@NEWS@</tag> release notes for the bundle -- a longer version +of @ANNOUNCE@. For GHC, the release notes are contained in the User +Guide and this file isn't present. + +<tag>@bin/<platform>@</tag> contains platform-specific executable +files to be invoked directly by the user. These are the files that +must end up in your path. + +<tag>@lib/<platform>/@</tag> 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 there would be a sub-directory +@ghc-x.xx@/ where @x.xx@ is the version number of GHC in the bundle. + +These sub-directories have the following general structure: + +<descrip> +<tag>@libHS.a@ etc:</tag> supporting library archives. +<tag>@ghc-iface.prl@ etc:</tag> support scripts. +<tag>@import/@</tag> <idx>Interface files</idx> (@.hi@) for the prelude. +<tag>@include/@</tag> A few C @#include@ files. +</descrip> + +<tag>@share/@</tag> contains platform-independent support files +for the installation. Again, there is a sub-directory for each +@fptools@ project. + +<tag>@info/@</tag> contains Emacs info documentation files (one +sub-directory per project). + +<tag>@html/@</tag> contains HTML documentation files (one +sub-directory per project). + +<tag>@man/@</tag> contains Unix manual pages. + +</descrip> + +This structure is designed so that you can unpack multiple bundles +(including ones from different releases or platforms) into a single +@fptools@ directory<footnote>this doesn't work at the +moment</footnote>: + +<tscreen><verb> + % cd /your/scratch/space + % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - + % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf - +</verb></tscreen> + +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. + +<sect2>Installing<p> +<label id="sec:install"> + +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@<ncdx/configure/ script by changing your +directory to @fptools@ and typing @./configure@. That should convert +@Makefile.in@ to @Makefile@. + +<nidx/installing in-place/ +<nidx/in-place installation/ + +You can now either start using the tools <em/in-situ/ without going +through any installation process, just type @make in-place@ to set the +tools up for this. You'll also want to add the path which @make@ will +now echo to your @PATH@ environment variable. This option is useful if +you simply want to try out the package and/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: + +<enum> +<item> Edit the @Makefile@ and check the settings of the following variables: + +<nidx/directories, installation/ +<nidx/installation directories/ + +<descrip> +<tag>@platform@</tag> the platform you are going to install for. + +<tag>@bindir@</tag> the directory in which to install user-invokable +binaries. + +<tag>@libdir@</tag> the directory in which to install +platform-dependent support files. + +<tag>@datadir@</tag> the directory in which to install +platform-independent support files. + +<tag>@infodir@</tag> the directory in which to install Emacs info +files. + +<tag>@htmldir@</tag> the directory in which to install HTML +documentation. + +<tag>@dvidir@</tag> the directory in which to install DVI +documentation. +</descrip> + +The values for these variables can be set through invocation of the +@configure@<ncdx/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!</em> + +<item>Run @make install@. This <em/ should/ work with ordinary Unix +@make@ -- no need for fancy stuff like GNU @make@. + +<item>@rehash@ (t?csh or zsh users), so your shell will see the new +stuff in your bin directory. + +<item> Once done, test your ``installation'' as suggested in Section +<ref id="sec:GHC-test" name="Testing GHC">. Be sure to use a @-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 in +Section <ref id="sec:build-pitfalls" name="Building Pitfalls">. +</enum> + +<nidx/link, installed as ghc/ +When installing the user-invokable binaries, this installation +procedure will install GHC as @ghc-x.xx@ where @x.xx@ is the version +number of GHC. It will also make a link (in the binary installation +directory) from @ghc@ to @ghc-x.xx@. 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-x.xx@ should always invoke GHC version @x.xx@. + +<sect1>What bundles there are +<p> + +<nidx/bundles, binary/ +There are plenty of ``non-basic'' GHC bundles. The files for them are +called @ghc-x.xx-<bundle>-<platform>.tar.gz@, where +the @<platform>@ is as above, and @<bundle>@ is one +of these: + +<descrip> + +<tag>@prof@:</tag> Profiling with cost-centres. You probably want this. +<nidx/profiling bundles/ +<nidx/bundles, profiling/ + +<tag>@conc@:</tag> Concurrent Haskell features. You may want this. +<nidx/concurrent bundles/ +<nidx/bundles, concurrent/ + +<tag>@par@:</tag> Parallel Haskell features (sits on top of PVM). +You'll want this if you're into that kind of thing. +<nidx/parallel bundles/ +<nidx/bundles, parallel/ + +<tag>@gran@:</tag> The ``GranSim'' parallel-Haskell simulator +(hmm... mainly for implementors). +<nidx/bundles, gransim/ +<nidx/gransim bundles/ + +<tag>@ticky@:</tag> ``Ticky-ticky'' profiling; very detailed +information about ``what happened when I ran this program''---really +for implementors. +<nidx/bundles, ticky-ticky/ +<nidx/ticky-ticky bundles/ + +<tag>@prof-conc@:</tag> Cost-centre profiling for Concurrent Haskell. +<nidx/bundles, profiled-concurrent/ +<nidx/profiled-concurrent bundles/ + +<tag>@prof-ticky@:</tag> Ticky-ticky profiling for Concurrent Haskell. +<nidx/bundles, profiled-ticky/ +<nidx/ticky-concurrent bundles/ +</descrip> + +One likely scenario is that you will grab <em/three/ binary +bundles---basic, profiling, and concurrent. We don't usually make the +rest, although you can build them yourself from a source distribution. + +<sect1>Testing that GHC seems to be working +<label id="sec:GHC-test"> +<p> +<nidx>testing a new GHC</nidx> + +The way to do this is, of course, to compile and run <em/this/ program +(in a file @Main.hs@): + +<tscreen><verb> +main = putStr "Hello, world!\n" +</verb></tscreen> + +Compile the program, using the @-v@ (verbose) flag to verify that +libraries, etc., are being found properly: +<tscreen><verb> +% ghc -v -o hello Main.hs +</verb></tscreen> + +Now run it: +<tscreen><verb> +% ./hello +Hello, world! +</verb></tscreen> + +Some simple-but-profitable tests are to compile and run the notorious +@nfib@<ncdx/nfib/ program, using different numeric types. Start with +@nfib :: Int -> Int@, and then try @Integer@, @Float@, @Double@, +@Rational@ and maybe @Complex Float@. Code for this is distributed in +@ghc/misc/examples/nfib/@ in a source distribution. + +For more information on how to ``drive'' GHC, either do @ghc -help@ or +consult the User's Guide (distributed in several pre-compiled formats +with a binary distribution, or in source form in +@ghc/docs/users_guide@ in a source distribution). + +<sect>Installing pre-supposed utilities +<label id="sec:pre-supposed"> +<nidx>pre-supposed utilities</nidx> +<nidx>utilities, pre-supposed</nidx> +<p> + +Here are the gory details about some utility programs you may need; +@perl@ and @gcc@ are the only important ones. (<idx/PVM/ is important +if you're going for Parallel Haskell.) The <tt><cdx/configure/</tt> +script will tell you if you are missing something. + +<descrip> +<tag>Perl:</tag> +<nidx>pre-supposed: Perl</nidx> +<nidx>Perl, pre-supposed</nidx> +<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 is Perl~4 friendly though. For +Win32 platforms, Perl~5 is recommended, we even strongly suggest you +pick up a port of Perl~5 for @cygwin32@, as the common Hip/ActiveWare +port of Perl is not Cool Enough for our purposes. + +Perl should be put somewhere so that it can be invoked by the @#!@ +script-invoking mechanism. (I believe @/usr/bin/perl@ is preferred; +we use @/usr/local/bin/perl@ at Glasgow.) The full pathname should +be less than 32 characters long. + +<tag>GNU C (@gcc@):</tag> +<nidx>pre-supposed: GCC (GNU C compiler)</nidx> +<nidx>GCC (GNU C compiler), pre-supposed</nidx> +The current version is 2.7.2. + +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 @iX86@ boxes---you may need to fiddle with GHC's +@-monly-N-regs@ option; ask if confused...) + +<nidx/EGCS/ +EGCS (the Enhanced GNU Compiler Suite) may or may not work, we haven't +tested it fully yet. + +<tag>PVM version 3:</tag> +<nidx>pre-supposed: PVM3 (Parallel Virtual Machine)</nidx> +<nidx>PVM3 (Parallel Virtual Machine), pre-supposed</nidx> +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 @research.att.com@, in +@netlib@. + +A PVM installation is slightly quirky, but easy to do. Just follow +the @Readme@ instructions. + +<tag>@xargs@ on Solaris2:</tag> +<nidx>xargs, presupposed (Solaris only)</nidx> +<nidx>Solaris: alternative xargs</nidx> +The GHC libraries are put together with something like: +<tscreen><verb> +find bunch-of-dirs -name '*.o' -print | xargs ar q ... +</verb></tscreen> +Unfortunately the Solaris @xargs@ (the shell-script equivalent +of @map@) only ``bites off'' the @.o@ files a few at a +time---with near-infinite rebuilding of the symbol table in +the @.a@ file. + +The best solution is to install a sane @xargs@ from the GNU +findutils distribution. You can unpack, build, and install the GNU +version in the time the Solaris @xargs@ mangles just one GHC +library. + +<tag>Autoconf:</tag> +<nidx>pre-supposed: Autoconf</nidx> +<nidx>Autoconf, pre-supposed</nidx> +GNU Autoconf is used to build the @configure@ script from +@configure.in@ in a source distribution. If you modify @configure.in@, you'll need @autoconf@ to regenerate @configure@. + +<tag>@bash@ (Parallel Haskell only):</tag> +<nidx>bash, presupposed (Parallel Haskell only)</nidx> +Sadly, the @gr2ps@ script, used to convert ``parallelism profiles'' +to PostScript, is written in Bash (GNU's Bourne Again shell). +This bug will be fixed (someday). + +<tag>Makeindex:</tag> +<nidx>pre-supposed: makeindex</nidx> +<nidx>makeindex, pre-supposed</nidx> +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. + +<tag>Tgrind:</tag> +<nidx>pre-supposed: tgrind</nidx> +<nidx>tgrind, pre-supposed</nidx> +This is required only if you remake lots of our documents <em/and/ +you use the @-t tgrind@ option with @lit2latex@ (also literate +programming), to do ``fancy'' typesetting of your code. <em/Unlikely./ + +<tag>Flex:</tag> +<nidx>pre-supposed: flex</nidx> +<nidx>flex, pre-supposed</nidx> +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. On our machines, the version in +@/bin@ doesn't work; you need the GNU version. Find out by saying +@flex --version@ (our current version is 2.5.3, but maybe earlier ones +will work). If it doesn't know about the @--version@ flag, it ain't +the right @flex@. + +<tag>Yacc:</tag> +<nidx>pre-supposed: non-worthless Yacc</nidx> +<nidx>Yacc, pre-supposed</nidx> +If you mess with the Haskell parser, you'll need a Yacc that can cope. +The unbundled @/usr/lang/yacc@ is OK; the GNU @bison@ is OK; +Berkeley yacc, @byacc@, is not OK. + +<tag>@sed@</tag> +<nidx>pre-supposed: sed</nidx> +<nidx>sed, pre-supposed</nidx> +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..) +</descrip> + +Two @fptools@ projects are worth a quick note at this point, because +they are useful for all the others: +<itemize> +<item> @glafp-utils@ contains several utilities which aren't +particularly Glasgow-ish, but Occasionally Indispensable. Like +@lndir@ for creating symbolic link trees. + +<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. +</itemize> + + + +<sect>Building from source +<label id="sec:building-from-source"> +<nidx>Building from source</nidx> +<nidx>Source, building from</nidx> +<p> + +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. + +<sect1>Your source tree +<label id="sec:source-tree"> +<p> + +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: + +<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@, @config.sub@, @config.guess@: +these files support the configuration process. +<item> @install-sh@. +</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 +suite, 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 +@literate@ (or an installed copy of the tools) in order to format the +GHC documentation. + +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. + +<sect1>Build trees +<nidx/build trees/ +<nidx/link trees, for building/ +<p> + +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@<ncdx/lndir/, @mkshadowdir@<ncdx/mkshadowdir/ are two (If you +don't have either, the source distribution includes sources for the +@X11@ @lndir@ --- check out @fptools/glafp-utils/lndir@ ). + +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 id="sec:build-config" name="Build +Configuration"> <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! + +Remember, that the source files in the build tree are <em/symbolic +links/ to the files in the source tree. (The build tree soon +accumulates lots of built files like @Foo.o@, as well.) You +can <em/delete/ a source file from the build tree without affecting +the source tree (though it's an odd thing to do). On the other hand, +if you <em/edit/ a source file from the build tree, you'll edit the +source-tree file directly. (You can set up Emacs so that if you edit +a source file from the build tree, Emacs will silently create an +edited copy of the source file in the build tree, leaving the source +file unchanged; but the danger is that you think you've edited the +source file whereas actually all you've done is edit the build-tree +copy. More commonly you do want to edit the source file.) + +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)@<ncdx/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@. + + +<sect1>Getting the build you want +<label id="sec:build-config"> +<p> + +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)<nidx>platform</nidx>. 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 three-step process. +<descrip> + +<tag>Step 1: get ready for configuration.</tag> Change directory to +@$(FPTOOLS_TOP)@ and issue the command @autoconf@<ncdx/autoconf/ (with +no arguments). This GNU program converts @$(FPTOOLS_TOP)/configure.in@ +to a shell script called @$(FPTOOLS_TOP)/configure@. + +Both these steps are completely platform-independent; they just mean +that the human-written file (@configure.in@) can be short, although +the resulting shell script, @configure@, and @mk/config.h.in@, are +long. + +In case you don't have @autoconf@ we distribute the results, +@configure@, and @mk/config.h.in@, with the source distribution. They +aren't kept in the repository, though. + +<tag>Step 2: system configuration.</tag> +Runs the newly-created @configure@ script, thus: +<tscreen><verb> + ./configure +</verb></tscreen> +@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: + +<itemize> + +<item> It translates @mk/config.mk.in@<ncdx/config.mk.in/ to +@mk/config.mk@<ncdx/config.mk/, substituting for things between +``@@@@@@@@}'' brackets. So, ``@@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@<ncdx/config.h.in/ to +@mk/config.h@<ncdx/config.h/. The latter is @#include@d by various C +programs, which can thereby make use of configuration information. + +</itemize> + +@configure@ caches the results of its run in @config.cache@. Quite +often you don't want that; you're running @configure@ a second time +because something has changed. In that case, simply delete +@config.cache@. + +<tag>Step 3: build configuration.</tag> + + Next, you say how this build of @fptools@ is to differ from the +standard defaults by creating a new file @mk/build.mk@<ncdx/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. + +</descrip> + +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 look at @mk/config.mk.in@, 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@<ncdx/boilerplate.mk/, includes @build.mk@ after +@config.mk@.) + +For example, @config.mk.in@ contains the definition: + +<tscreen><verb> + ProjectsToBuild = glafp-utils literate ghc hslibs +</verb></tscreen> + +The accompanying comment explains that this is the list of enabled +projects; that is, if (after configuring) you type @gmake all@ in +@FPTOOLS_TOP@ four specified projects will be made. If you want to +add @green-card@, you can add this line to @build.mk@: + +<tscreen><verb> + ProjectsToBuild += green-card +</verb></tscreen> + +or, if you prefer, + +<tscreen><verb> + ProjectsToBuild = glafp-utils literate ghc hslibs green-card +</verb></tscreen> + +(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 +``@@...@@'' 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: + +<tscreen><verb> + YACC = @YaccCmd@ +</verb></tscreen> + +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@: + +<tscreen><verb> + YACC = myyacc +</verb></tscreen> + +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@. + +You can also use @build.mk@ to override anything that @configure@ got +wrong. One place where this happens often is with the definition of +@FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path +to the top of your source tree, but if your system uses an automounter +then the correct directory is hard to find automatically. If you find +that @configure@ has got it wrong, just put the correct definition in +@build.mk@. + +<sect1>The story so far +<p> + +Let's summarise the steps you need to carry to get yourself +a fully-configured build tree from scratch. + +<enum> + +<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@). Make sure that you have +the essential files (see Section~<ref id="sec:source-tree" +name="Source Tree">). + +<item> Use @lndir@ or @mkshadowdir@ to create a build tree. +<tscreen><verb> + cd myfptools + mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 +</verb></tscreen> +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. +<tscreen><verb> + cd /scratch/joe-bloggs/myfptools-sun4 +</verb></tscreen> +<item> Prepare for system configuration: +<tscreen><verb> + autoconf +</verb></tscreen> +(You can skip this step if you are starting from a source distribution, +and you already have @configure@ and @mk/config.h.in@.) + +<item> Do system configuration: +<tscreen><verb> + ./configure +</verb></tscreen> + +<item> Create the file @mk/build.mk@, +adding definitions for your desired configuration options. +<tscreen><verb> + emacs mk/build.mk +</verb></tscreen> +</enum> +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. + +<sect1>Making things +<p> + +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. + +<sect1>Standard Targets +<label id="sec:standard-targets"> +<nidx/targets, standard makefile/ +<nidx/makefile targets/ +<p> + +In any directory you should be able to make the following: +<descrip> +<tag>@boot@:</tag> 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 can't 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, +but note that this is a one-off, i.e., there's no need to re-do +@gmake boot@ if you should re-configure your build tree at a later +stage (no harm caused if you do though). + +<tag>@all@:</tag> 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@. + +<tag>@install@:</tag> 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@. + +<tag>@uninstall@:</tag> reverses the effect of @install@. + +<tag>@clean@:</tag> remove all easily-rebuilt files. + +<tag>@veryclean@:</tag> 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). + +<tag>@check@:</tag> run the test suite. + +</descrip> + +All of these standard targets automatically recurse into +sub-directories. Certain other standard targets do not: + +<descrip> + +<tag>@configure@:</tag> is only available in the root directory +@$(FPTOOLS_TOP)@; it has been discussed in Section~<ref +id="sec:build-config" name="Build Configuration">. + +<tag>@depend@:</tag> 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: + +<tscreen><verb> + Foo.o : Baz.hi +</verb></tscreen> + +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. + +<tag>@binary-dist@:</tag> make a binary distribution. This is the +target we use to build the binary distributions of GHC and Happy. + +<tag>@dist@:</tag> make a source distribution. You must be in a +linked buid tree to make this target. +</descrip> + +Most @Makefiles@ have targets other than these. You can find +this out by looking in the @Makefile@ itself. + +<sect>The @Makefile@ architecture +<nidx/makefile architecture/ +<p> + +@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. + +<sect1>A small project +<p> + +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: + +<nidx/Makefile, minimal/ +<tscreen><verb> + # Makefile for fptools project "small" + + TOP = .. + include $(TOP)/mk/boilerplate.mk + + SRCS = $(wildcard *.lhs) $(wildcard *.c) + HS_PROG = small + + include $(TOP)/target.mk +</verb></tscreen> + +This @Makefile@ has three sections: + +<enum> + +<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.</footnote> a file of ``boilerplate'' code from the level +above (which in this case will be +@FPTOOLS_TOP/mk/boilerplate.mk@<ncdx/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 id="sec:boiler" name="Boilerplate">. +<nidx/include, directive in Makefiles/ +<nidx/Makefile inclusion/ + +Before the @include@ statement, you must define the @make@ variable +@TOP@<ncdx/TOP/ to be the directory containing the @mk@ directory in +which the @boilerplate.mk@ file is. It is <em/not/ OK to simply say + +<tscreen><verb> + include ../mk/boilerplate.mk # NO NO NO +</verb></tscreen> + +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.</em> 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@<ncdx/SRCS/ (the source files from which is to be +built), and @HS_PROG@<ncdx/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 +id="sec:targets" name="Targets">. + +The definition for @SRCS@ uses the useful GNU @make@ construct +@$(wildcard@~$pat$@)@<ncdx/wildcard/, 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@<ncdx/target.mk/. It contains the rules that tell +@gmake@ how to make the standard targets (Section~<ref +id="sec:standard-targets" name="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 id="sec:boiler-arch" +name="Boilerplate Architecture">. + +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 +id="sec:targets" name="Targets">. + +</enum> + +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: + +<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@.) + +</itemize> + +All @Makefile@s should follow the above three-section format. + +<sect1>A larger project +<p> + +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: + +<tscreen><verb> + $(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... +</verb></tscreen> + +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@s 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: + +<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@. + +</itemize> + +So these two files are the place to look for @ghc@-wide customisation +of the standard boilerplate. + +<sect1>Boilerplate architecture +<nidx/boilerplate architecture/ +<label id="sec:boiler-arch"> +<p> + +Every @Makefile@ includes a @boilerplate.mk@<ncdx/boilerplate.mk/ file +at the top, and @target.mk@<ncdx/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: + +<itemize> + +<item> @boilerplate.mk@ consists of: +<itemize> +<item> <em/Definitions of millions of @make@ variables/ that +collectively specify the build configuration. Examples: +<tt><cdx/HC_OPTS/</tt>, the options to feed to the Haskell compiler; +<tt><cdx/NoFibSubDirs/</tt>, the sub-directories to enable within the +@nofib@ project; <tt><cdx/GhcWithHc/</tt>, 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. +</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: + +<tscreen><verb> + SRC_HC_OPTS += -O +</verb></tscreen> + +thereby adding ``@-O@'' to the end of <tt><cdx/SRC_HC_OPTS/</tt>. + +<item> @target.mk@ contains @make@ rules for the standard +targets described in Section~<ref id="sec:standard-targets" +name="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: + +<itemize> +<item> @gmake@ commits target and dependency lists earlier than +it should. For example, @target.mk@ has a rule that looks like +this: + +<tscreen><verb> + $(HS_PROG) : $(OBJS) + $(HC) $(LD_OPTS) $< -o $@ +</verb></tscreen> + +If this rule was in @boilerplate.mk@ then @$(HS_PROG)@<ncdx/HS_PROG/ +and @$(OBJS)@<ncdx/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. +</itemize> +</itemize> + +<sect1>The main @mk/boilerplate.mk@ file +<label id="sec:boiler"> +<ncdx/boilerplate.mk/ +<p> + +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: + +<descrip> + +<tag><tt><cdx/config.mk/</tt></tag> is the build configuration file we +discussed at length in Section~<ref id="sec:build-config" name="Build +Configuration">. + +<tag><tt><cdx/paths.mk/</tt></tag> defines @make@ variables for +pathnames and file lists. In particular, it gives definitions for: + +<descrip> +<tag><tt><cdx/SRCS/</tt>:</tag> all source files in the current directory. +<tag><tt><cdx/HS_SRCS/</tt>:</tag> 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. +<tag><tt><cdx/C_SRCS/</tt>:</tag> similarly for C source files. +<tag><tt><cdx/HS_OBJS/</tt>:</tag> the @.o@ files derived from @$(HS_SRCS)@. +<tag><tt><cdx/C_OBJS/</tt>:</tag> similarly for @$(C_SRCS)@. +<tag><tt><cdx/OBJS/</tt>:</tag> the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@. +</descrip> + +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@. + +<tag><tt><cdx/opts.mk/</tt></tag> defines @make@ variables for option +strings to pass to each program. For example, it defines +<tt><cdx/HC_OPTS/</tt>, the option strings to pass to the Haskell +compiler. See Section~<ref id="sec:suffix" name="Pattern Rules and +Options">. + +<tag><tt><cdx/suffix.mk/</tt></tag> defines standard pattern rules -- +see Section~<ref id="sec:suffix" name="Pattern Rules and Options">. +</descrip> + +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@. + +<sect1>Pattern rules and options +<label id="sec:suffix"> +<nidx/Pattern rules/ +<p> + +The file @suffix.mk@<ncdx/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: + +<tscreen><verb> +%.o : %.c + $(RM) $@ + $(CC) $(CC_OPTS) -c $< -o $@ +</verb></tscreen> + +Here's how to understand the rule. It says that +<em/something/@.o@ (say @Foo.o@) can be built from +<em/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: + +<tscreen><verb> + CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) +</verb></tscreen> + +The four variables from which @CC_OPTS@ is built have the following meaning: + +<descrip> + +<tag><tt><cdx/SRC_CC_OPTS/</tt>:</tag> options passed to all C +compilations. + +<tag>@WAY_<way>_CC_OPTS@:</tag> 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 id="sec:ways" name="Ways"> dicusses multi-way +compilation.) <tag>@<module>_CC_OPTS@:</tag> 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@. + +<tag><tt><cdx/EXTRA_CC_OPTS/</tt>:</tag> extra options to pass to all +C compilations. This is intended for command line use, thus; + +<tscreen><verb> + gmake libHS.a EXTRA_CC_OPTS="-v" +</verb></tscreen> +</descrip> + +<sect1>The main @mk/target.mk@ file +<label id="sec:targets"> +<ncdx/target.mk/ +<p> + +@target.mk@ contains canned rules for all the standard targets +described in Section~<ref id="sec:standard-targets" name="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. + +<descrip> +<tag><tt><cdx/HS_PROG/</tt>.</tag> If @HS_PROG@ is defined, you get +rules with the following targets: +<descrip> +<tag><tt><cdx/HS_PROG/</tt></tag> itself. This rule links @$(OBJS)@ +with the Haskell runtime system to get an executable called +@$(HS_PROG)@. +<tag><tt><cdx/install/</tt></tag> installs @$(HS_PROG)@ +in @$(bindir)@ with the execute bit set. +</descrip> + +<tag><tt><cdx/C_PROG/</tt></tag> is similar to @HS_PROG@, except that +the link step links @$(C_OBJS)@ with the C runtime system. + +<tag><tt><cdx/LIBRARY/</tt></tag> 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. + +<tag><tt><cdx/LIB_DATA/</tt></tag> ... +<tag><tt><cdx/LIB_EXEC/</tt></tag> ... + +<tag><tt><cdx/HS_SRCS/</tt>, <tt><cdx/C_SRCS/</tt>.</tag> 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@. +</descrip> + +All of these rules are ``double-colon'' rules, thus + +<tscreen><verb> + install :: $(HS_PROG) + ...how to install it... +</verb></tscreen> + +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. + +<sect1>Recursion +<label id="sec:subdirs"> +<nidx/recursion, in makefiles/ +<nidx/Makefile, recursing into subdirectories/ +<p> + +In leaf @Makefiles@ the variable @SUBDIRS@<ncdx/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 +id="sec:standard-targets" name="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. + +<sect1>Way management +<label id="sec:ways"> +<nidx/way management/ +<p> + +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 @target.mk@<ncdx/target.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: + +<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 id="sec:subdirs" +name="Subdirectories">). + +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: + +<tscreen><verb> + %.$(way_)o : %.lhs + $(HC) $(HC_OPTS) $< -o $@ +</verb></tscreen> + +Neat, eh? +</itemize> + + +<sect1>When the canned rule isn't right +<p> + +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. + + +<sect>Booting/porting from C (@.hc@) files +<label id="sec:booting-from-C"> +<nidx>building GHC from .hc files</nidx> +<nidx>booting GHC from .hc files</nidx> +<nidx>porting GHC</nidx> +<p> + +This section is for people trying to get GHC going by using the +supplied intermediate C (@.hc@) files. This would probably be because +no binaries have been provided, or because the machine is not ``fully +supported.'' + +The intermediate C files are normally made available together with a +source release, please check the announce message for exact directions +of where to find them. If we've haven't made them available or you +can't find them, please ask. + +Assuming you've got them, unpack them on top of a fresh source tree. +Then follow the `normal' instructions in Section~<ref +id="sec:building-from-source" name="Buiding From Source"> for setting +up a build tree and configuring it. The only extra thing to remember +when booting from @.hc@ files is to add the following line to the +@build.mk@ file: + +<tscreen><verb> +GhcWithHscBuiltViaC=YES +</verb></tscreen> +<ncdx/GhcWithHscBuiltViaC/ + +and proceed with doing a @make boot@ followed by a @make all@. + +That's the mechanics of the boot process, but, of course, if you're +trying to boot on a platform that is not supported and significantly +`different' from any of the supported ones, this is only the start of +the adventure...(ToDo: porting tips - stuff to look out for, etc.) + +<sect>Known pitfalls in building Glasgow Haskell +<label id="sec:build-pitfalls"> +<nidx>problems, building</nidx> +<nidx>pitfalls, in building</nidx> +<nidx>building pitfalls</nidx> +<p> + +WARNINGS about pitfalls and known ``problems'': + +<enum> + +<item> +One difficulty that comes up from time to time is running out of space +in @/tmp@. (It is impossible for the configuration stuff to +compensate for the vagaries of different sysadmin approaches re temp +space.) +<nidx/tmp, running out of space in/ + +The quickest way around it is @setenv TMPDIR /usr/tmp@<ncdx/TMPDIR/ or +even @setenv TMPDIR .@ (or the equivalent incantation with the shell +of your choice). + +The best way around it is to say +<tscreen><verb> +export TMPDIR=<dir> +</verb></tscreen> +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 @ghc/runtime/gmp@ and +even in @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, @ar@chiving warning messages like the following are not +a problem: +<tscreen><verb> +ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ +ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ +... +</verb></tscreen> + + +<item> +Also harmless are some specialisation messages that you may see when +compiling GHC; e.g.: +<tscreen><verb> +SPECIALISATION MESSAGES (Desirable): +*** INSTANCES +{-# SPECIALIZE instance Eq [Class] #-} +{-# SPECIALIZE instance Eq (Class, [Class]) #-} +{-# SPECIALIZE instance Outputable [ClassOp] #-} +{-# SPECIALIZE instance Outputable [Id] #-} +</verb></tscreen> + + +<item> In compiling the compiler proper (in @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 @-H@ flag to the @<module>_HC_OPTS@ @make@ variable +in the appropriate @Makefile@; (2)~try again: @gmake@. (Section~<ref +id="sec:suffix" name="Pattern Rules and Options">.) + +Alternatively, just cut to the chase scene: +<tscreen><verb> +% cd ghc/compiler +% make EXTRA_HC_OPTS=-H32m # or some nice big number +</verb></tscreen> + + +<item> +Not too long into the build process, you may get a huge complaint +of the form: +<tscreen><verb> +Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27. +</verb></tscreen> +This indicates that your @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 @/usr/include/math.h@, then your GCC was +mis-installed. @fixincludes@ wasn't run when it should've been. + +As @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-@ranlib@<ncdx/ranlib/ your libraries (on Sun4s). + +<tscreen><verb> +% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 +% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... +? ranlib $i +? # or, on some machines: ar s $i +? end +</verb></tscreen> + +We'd be interested to know if this is still necessary. + + +<item> +If you end up making documents that involve (La)TeX and/or @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 @make -n whatever.dvi@ to see the intended commands, then try to +muddle through, doing them by hand. + + +<item> +GHC's sources go through @cpp@ before being compiled, and @cpp@ varies +a bit from one Unix to another. One particular gotcha is macro calls +like this: + +<tscreen><verb> + SLIT("Hello, world") +</verb></tscreen> + +Some @cpp@s treat the comma inside the string as separating two macro +arguments, so you get + +<tscreen><verb> + :731: macro `SLIT' used with too many (2) args +</verb></tscreen> + +Alas, @cpp@ doesn't tell you the offending file! + +Workaround: don't put wierd things in string args to @cpp@ macros. +</enum> + +</article>