From 2acd69d065a8460fce3876798b4cb0c248279703 Mon Sep 17 00:00:00 2001 From: rrt Date: Tue, 25 Jan 2000 12:01:28 +0000 Subject: [PATCH] [project @ 2000-01-25 12:01:28 by rrt] Renamed to building.sgml --- docs/installing.sgml | 3074 -------------------------------------------------- 1 file changed, 3074 deletions(-) delete mode 100644 docs/installing.sgml diff --git a/docs/installing.sgml b/docs/installing.sgml deleted file mode 100644 index 15d8dd5..0000000 --- a/docs/installing.sgml +++ /dev/null @@ -1,3074 +0,0 @@ - - -
- - - -Building and Installing the Glasgow Functional Programming Tools Suite -Version 4.04 -The GHC Team -
glasgow-haskell-{users,bugs}@dcs.gla.ac.uk
-January 2000 - - - - -This guide is intended for people who want to build or modify -programs from the Glasgow fptools suite (as distinct from those -who merely want to run them). Installation instructions are now provided in the user guide. - - - -The bulk of this guide applies to building on Unix systems; see for Windows notes. - - - - - - - - -Getting the Glasgow <Literal>fptools</Literal> suite - - - -Building the Glasgow tools 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: - - - - - - -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. The user guide -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. - - - -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 one or more -projects in the fptools suite. Not only that, but the more awkward -machine-independent steps are done for you. For example, if you don't -have flexflex 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 4.xx can be compiled up using 2.10 or later. - - - -Build GHC from intermediate C .hc fileshc 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 -. - - - -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). - - - -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. - - - -More information about our CVS repository is available at The Fptools CVS Cheat Sheet. - - - - - - -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. - - - - - -Things to check before you start typing - - -Here's a list of things to check before you get started. - - - - - -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 estimates of disk-space needs. (I don't yet -know the disk requirements for the non-GHC tools). - - - - - - -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. -gives the full run-down on ports or lack thereof. - -NOTE: as of version 4.00, we lost a few ports. All of the x86 ports -are working, as is the Sparc/Solaris port, but the rest will need a -little work. Please contact us if you can provide hardware cycles -and/or porting expertise. - - - - - - - Be sure that the ``pre-supposed'' utilities are installed. - elaborates. - - - - - - - If you have any problem when building or installing the Glasgow -tools, please check the ``known pitfalls'' (). Also check the known bugs page. -known bugs -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. -bugs, reporting - -If in doubt, please send a message to glasgow-haskell-bugs@dcs.gla.ac.uk. -bugs, mailing list - - - - - - - - - - -What machines the Glasgow tools run on - - - -ports, GHC -GHC ports -supported platforms -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. - - - -What platforms the Haskell compiler (GHC) runs on - - -fully-supported platforms -native-code generator -registerised ports -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 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 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… - - - - - - -alpha-dec-osf1: - - -alpha-dec-osf1: fully supported - - - -(We have OSF/1 V3.0.) Fully supported, including native-code -generator. We recommend GCC 2.6.x or later. - - - -sparc-sun-sunos4: - - -sparc-sun-sunos4: fully supported - - - -Fully supported, including native-code generator. - - - -sparc-sun-solaris2: - - -sparc-sun-solaris2: fully supported - - - -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 xargsxargs program is -atrociously bad for building GHC libraries (see for -details). - - - -HP-PA box running HP - - -UX 9.x:/ -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 -jaguar.cs.utah.edu. We think a straight GCC 2.7.x works, -too. - - - -Concurrent/Parallel Haskell probably don't work (yet). -hppa1.1-hp-hpux: concurrent—no -hppa1.1-hp-hpux: parallel—no - - - -i386-*-linux (PCs running Linux—ELF format): - - -i386-*-linux: registerised port - - - -GHC works registerised. You must have GCC 2.7.x or later. The -iX86 native-code generator is nearly there, but it isn't turned -on by default. - - - -Profiling works, and Concurrent Haskell works. -i386-*-linux: profiling—yes -i386-*-linux: concurrent—yes -Parallel Haskell probably works. -i386-*-linux: parallel—maybe - - - -On old Linux a.out systems: should be the same. -i386-*-linuxaout: registerised port - - - -i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and -NetBSD/OpenBSD using FreeBSD emulation): - - -i386-*-freebsd:registerised port - - - -GHC works registerised. Supports same set of bundles as the above. - - - -i386-*-freebsd: profiling—yes -i386-*-freebsd: concurrent—yes -i386-*-freebsd: parallel—maybe - - - -i386-unknown-cygwin32: - - -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. - - - -i386-*-cygwin32: profiling—yes -i386-*-cygwin32: concurrent—yes - - - -mips-sgi-irix5: - - -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 -; turns out that is important! - - - -Concurrent/Parallel Haskell probably don't work (yet). -Profiling might work, but it is untested. -mips-sgi-irix5: concurrent—no -mips-sgi-irix5: parallel—no -mips-sgi-irix5: profiling—maybe - - - -mips-sgi-irix6: - - -mips-sgi-irix6: registerised port - - - -Thanks to the fine efforts of Tomasz Cholewo tjchol01@mecca.spd.louisville.edu, GHC works registerised (no -native code generator) under IRIX 6.2 and 6.3. Depends on having a -specially tweaked version of gcc-2.7.2 around. - - - -Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested). -mips-sgi-irix6: concurrent—maybe -mips-sgi-irix6: parallel—maybe -mips-sgi-irix6: profiling—yes - - - -powerpc-ibm-aix: - - -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. -mips-sgi-irix5: concurrent—no -mips-sgi-irix5: parallel—no -mips-sgi-irix5: profiling—maybe - - - -m68k-apple-macos7 (Mac, using MPW): - - -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. - - - -m68k-next-nextstep3: - - -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). -m68k-next-nextstep3: concurrent—no -m68k-next-nextstep3: parallel—no - - - -m68k-sun-sunos4 (Sun3): - - -m68k-sun-sunos4: registerised -port GHC 2.0x and 3.0x haven't been tried on a Sun3. GHC 0.26 -worked registerised. No native-code generator. - - - -Concurrent/Parallel Haskell probably don't work (yet). -m68k-sun-sunos4: concurrent—no -m68k-sun-sunos4: parallel—no - - - - - - - - -What machines the other tools run on - - -Unless you hear otherwise, the other tools work if GHC works. - - - -Haggis requires Concurrent Haskell to work. -Haggis, Concurrent Haskell - - - - - - - - -Installing pre-supposed utilities - -<IndexTerm><Primary>pre-supposed utilities</Primary></IndexTerm> -<IndexTerm><Primary>utilities, pre-supposed</Primary></IndexTerm> - - -Here are the gory details about some utility programs you may need; -perl and gcc are the only important ones. (PVMPVM is important -if you're going for Parallel Haskell.) The configureconfigure -script will tell you if you are missing something. - - - - - - -Perl: - - -pre-supposed: Perl -Perl, pre-supposed -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 required. For Win32 platforms, we 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 -may need to be less than 32 characters long on some systems. - - - -GNU C (gcc): - - -pre-supposed: GCC (GNU C compiler) -GCC (GNU C compiler), pre-supposed - - - -Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other -versions at your own risk! - - - -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 - option; see the User's Guide) - - - -xargs on Solaris2: - - -xargs, presupposed (Solaris only) -Solaris: alternative xargs -The GHC libraries are put together with something like: - - -find bunch-of-dirs -name '*.o' -print | xargs ar q ... - - -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. - - - -Autoconf: - - -pre-supposed: Autoconf -Autoconf, pre-supposed - - - -GNU Autoconf is needed if you intend to build from the CVS sources, it -is not needed if you just intend to build a standard source -distribution. - - - -Autoconf builds the configure script from configure.in and -aclocal.m4. If you modify either of these files, you'll need -Autoconf to rebuild configure. - - - -sed - - -pre-supposed: sed -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.) - - - - - - -One fptools project is worth a quick note at this point, because it -is useful for all the others: glafp-utils contains several utilities -which aren't particularly Glasgow-ish, but Occasionally Indispensable. -Like lndir for creating symbolic link trees. - - - -Tools for building parallel GHC (GPH) - - - - - - -PVM version 3: - - -pre-supposed: PVM3 (Parallel Virtual Machine) -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 research.att.com, in -netlib. - - - -A PVM installation is slightly quirky, but easy to do. Just follow -the Readme instructions. - - - -bash: - - -bash, presupposed (Parallel Haskell only) -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). - - - - - - - - -Tools for building the Documentation - - - -The following additional tools are required if you want to format the -documentation that comes with the fptools projects: - - - - - - -DocBook: - - -pre-supposed: DocBook -DocBook, pre-supposed -All our documentation is written in SGML, using the DocBook DTD and processed using the Cygnus DocBook tools, which is the most shrink-wrapped SGML suite -that we could find. Unfortunately, it's only packaged as RPMs. You can use it to generate HTML (and -hence DVI, PDF and Postscript) and RTF from any -LinuxDoc source file (including this manual). - - - -TeX: - - -pre-supposed: TeX -TeX, pre-supposed -A decent TeX distribution is required if you want to produce printable -documentation. We recomment teTeX, which includes just about -everything you need. - - - - - - - - -Other useful tools - - - - - - -Flex: - - -pre-supposed: flex -flex, pre-supposed - - - -This is a quite-a-bit-better-than-Lex lexer. Used to build a couple -of utilities in glafp-utils. Depending on your operating system, -the supplied lex may or may not work; you should get the GNU -version. - - - - - - - - - - -Building from source - -<IndexTerm><Primary>Building from source</Primary></IndexTerm> -<IndexTerm><Primary>Source, building from</Primary></IndexTerm> - - -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. 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. - - - -Your source tree - - - -The source code is held in your source tree. -The root directory of your source tree must -contain the following directories and files: - - - - - - - - -Makefile: the root Makefile. - - - - - -mk/: the directory that contains the -main Makefile code, shared by all the -fptools software. - - - - - - configure.in, config.sub, config.guess: -these files support the configuration process. - - - - - - install-sh. - - - - - - - - -All the other directories are individual 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. - - - -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. - - - - - -Build trees -<IndexTerm><Primary>build trees</Primary></IndexTerm> -<IndexTerm><Primary>link trees, for building</Primary></IndexTerm> - - -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 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: -lndirlndir, mkshadowdirmkshadowdir are two (If you -don't have either, the source distribution includes sources for the -X11 lndir—check out fptools/glafp-utils/lndir). See for a typical invocation. - - - -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— 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 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 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 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 be (a -linked copy of) the root directory of the fptools suite. Inside -Makefiles, the root of your build tree is called -$(FPTOOLS_TOP)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. - - - - - -Getting the build you want - - - -When you build fptools you will be compiling code on a particular -host platform, to run on a particular target platform -(usually the same as the host platform)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 configuration of your build. -You set the configuration using a three-step process. - - - -Step 1: get ready for configuration. - - -Change directory to -$(FPTOOLS_TOP) and issue the command autoconfautoconf (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. - - - -Step 2: system configuration. - - -Runs the newly-created configure script, thus: - - -./configure - - -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: - - - - - - - - - It translates mk/config.mk.inconfig.mk.in to -mk/config.mkconfig.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. - - - - - - - It translates mk/config.h.inconfig.h.in to -mk/config.hconfig.h. The latter is #included by various C -programs, which can thereby make use of configuration information. - - - - - - - - - -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. - - - -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.mkbuild.mk -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. - - - - - - -And that's it for configuration. Simple, eh? - - - -What do you put in your build-specific configuration file -mk/build.mk? 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.mkboilerplate.mk, includes build.mk after -config.mk.) - - - -For example, config.mk.in contains the definition: - - - - - -ProjectsToBuild = glafp-utils ghc hslibs - - - - - -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: - - - - - -ProjectsToBuild += green-card - - - - - -or, if you prefer, - - - - - -ProjectsToBuild = glafp-utils ghc green-card - - - - - -(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 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: - - - - - -YACC = @YaccCmd@ - - - - - -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: - - - - - -YACC = myyacc - - - - - -You do not 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. - - - - - -The story so far - - -Let's summarise the steps you need to carry to get yourself -a fully-configured build tree from scratch. - - - - - - - - - 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 ). - - - - - - - Use lndir or mkshadowdir to create a build tree. - - -cd myfptools -mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 - - -(N.B. mkshadowdir's first argument is taken relative to its second.) 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. - - - - - - - Change directory to the build tree. Everything is going -to happen there now. - - -cd /scratch/joe-bloggs/myfptools-sun4 - - - - - - - - Prepare for system configuration: - - -autoconf - - -(You can skip this step if you are starting from a source distribution, -and you already have configure and mk/config.h.in.) - - - - - - - Do system configuration: - - -./configure - - - - - - - - - Create the file mk/build.mk, -adding definitions for your desired configuration options. - - -emacs mk/build.mk - - - - - - - -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. - - - - - -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 -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. - - - - - -Standard Targets - -<IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm> -<IndexTerm><Primary>makefile targets</Primary></IndexTerm> - - -In any directory you should be able to make the following: - - - -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. It also builds the necessary tools for compilation to proceed. - - - -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). - - - -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. - - - -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. - - - -uninstall: - - -reverses the effect of install. - - - -clean: - - -remove all easily-rebuilt files. - - - -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). - - - -check: - - -run the test suite. - - - - - - -All of these standard targets automatically recurse into -sub-directories. Certain other standard targets do not: - - - - - - -configure: - - -is only available in the root directory -$(FPTOOLS_TOP); it has been discussed in . - - - -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: - - - - - -Foo.o : Baz.hi - - - - - -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. - - - -binary-dist: - - -make a binary distribution. This is the -target we use to build the binary distributions of GHC and Happy. - - - -dist: - - -make a source distribution. You must be in a -linked build tree to make this target. - - - - - - -Most Makefiles have targets other than these. You can discover them by looking in the Makefile itself. - - - - - -Fast Making -<IndexTerm><Primary>fastmake</Primary></IndexTerm> -<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm> -<IndexTerm><Primary>FAST, makefile variable</Primary></IndexTerm> - - -Sometimes the dependencies get in the way: if you've made a small -change to one file, and you're absolutely sure that it won't affect -anything else, but you know that make is going to rebuild everything -anyway, the following hack may be useful: - - - - - -gmake FAST=YES - - - - - -This tells the make system to ignore dependencies and just build what -you tell it to. In other words, it's equivalent to temporarily -removing the .depend file in the current directory (where -mkdependHS and friends store their dependency information). - - - -A bit of history: GHC used to come with a fastmake script that did -the above job, but GNU make provides the features we need to do it -without resorting to a script. Also, we've found that fastmaking is -less useful since the advent of GHC's recompilation checker (see the -User's Guide section on "Separate Compilation"). - - - - - - - -The <Filename>Makefile</Filename> architecture -<IndexTerm><Primary>makefile architecture</Primary></IndexTerm> - - -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 weird 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. - - - -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: - - - -Makefile, minimal - - -# Makefile for fptools project "small" - -TOP = .. -include $(TOP)/mk/boilerplate.mk - -SRCS = $(wildcard *.lhs) $(wildcard *.c) -HS_PROG = small - -include $(TOP)/target.mk - - - - - -This Makefile has three sections: - - - - - - - - - The first section includes - - - -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.mkboilerplate.mk). As its name -suggests, boilerplate.mk consists of a large quantity of standard -Makefile code. We discuss this boilerplate in more detail in -. -include, directive in Makefiles -Makefile inclusion - -Before the include statement, you must define the make variable -TOPTOP to be the directory containing the mk directory in -which the boilerplate.mk file is. It is not OK to simply say - - - -include ../mk/boilerplate.mk # NO NO NO - - - -Why? Because the boilerplate.mk file needs to know where it is, so -that it can, in turn, include other files. (Unfortunately, when an -included 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, 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 Makefiles are written to have -the following property: after foo.mk is included, 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. - - - - - - - The second section defines the following standard make -variables: SRCSSRCS (the source files from which is to be -built), and HS_PROGHS_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 . - -The definition for SRCS uses the useful GNU make construct -$(wildcard $pat$)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.) - - - - - - - The last section includes a second file of standard code, -called target.mktarget.mk. It contains the rules that tell -gmake how to make the standard targets (). Why, you ask, -can't this standard code be part of boilerplate.mk? Good question. -We discuss the reason later, in . - -You do not 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 (). - - - - - - - - - -In our example Makefile, most of the work is done by the two -included files. When you say gmake all, the following things -happen: - - - - - - - - - gmake figures out that the object files are Foo.o and -Baz.o. - - - - - - - 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.) - - - - - - - It uses another standard pattern rule to compile Baz.c to -Baz.o, using a C compiler. (Ditto.) - - - - - - - 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 libraries 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.) - - - - - - - - - -All Makefiles should follow the above three-section format. - - - - - -A larger project - - -Larger projects are usually structured into a number 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: - - - - - -$(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... - - - - - -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 Makefiles in the -sub-directories. We say that ghc/Makefile is a non-leaf -Makefile, because it does little except organise its children, -while the Makefiles in the sub-directories are all leaf -Makefiles. (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 Makefiles 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: - - - - - - - - - ghc/mk/boilerplate.mk is included at the top of -ghc/Makefile, and of all the leaf Makefiles in the -sub-directories. It in turn includes the main boilerplate file -mk/boilerplate.mk. - - - - - - - - ghc/mk/target.mk is included at the bottom of -ghc/Makefile, and of all the leaf Makefiles in the -sub-directories. It in turn includes the file mk/target.mk. - - - - - - - - - -So these two files are the place to look for GHC-wide customisation -of the standard boilerplate. - - - - - -Boilerplate architecture -<IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm> - - - -Every Makefile includes a boilerplate.mkboilerplate.mk file -at the top, and target.mktarget.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: - - - - - - - - - boilerplate.mk consists of: - - - - - - Definitions of millions of make variables that -collectively specify the build configuration. Examples: -HC_OPTSHC_OPTS, the options to feed to the Haskell compiler; -NoFibSubDirsNoFibSubDirs, the sub-directories to enable within the -nofib project; GhcWithHcGhcWithHc, the name of the Haskell -compiler to use when compiling GHC in the ghc project. - - - - - -Standard pattern rules that tell gmake how to construct one -file from another. - - - - - - -boilerplate.mk needs to be included at the 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 replacing boilerplate definitions, it is also quite -common to augment them. For example, a Makefile might say: - - - -SRC_HC_OPTS += -O - - - -thereby adding ``'' to the end of SRC_HC_OPTSSRC_HC_OPTS. - - - - - - - target.mk contains make rules for the standard -targets described in . 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 includes. - -target.mk must be included at the end (rather than being part of -boilerplate.mk) for several tiresome reasons: - - - - - - - gmake commits target and dependency lists earlier than -it should. For example, target.mk has a rule that looks like -this: - - - -$(HS_PROG) : $(OBJS) - $(HC) $(LD_OPTS) $< -o $@ - - - -If this rule was in boilerplate.mk then $(HS_PROG)HS_PROG -and $(OBJS)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. - - - - - - - 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. - - - - - - - There are a couple of other reasons I've forgotten, but it doesn't -matter too much. - - - - - - - - - - - - - - - -The main <Filename>mk/boilerplate.mk</Filename> file - -<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> - - -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: - - - - - - -config.mkconfig.mk - - -is the build configuration file we -discussed at length in . - - - -paths.mkpaths.mk - - -defines make variables for -pathnames and file lists. In particular, it gives definitions for: - - - - - - -SRCSSRCS: - - -all source files in the current directory. - - - -HS_SRCSHS_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. - - - -C_SRCSC_SRCS: - - -similarly for C source files. - - - -HS_OBJSHS_OBJS: - - -the .o files derived from $(HS_SRCS). - - - -C_OBJSC_OBJS: - - -similarly for $(C_SRCS). - - - -OBJSOBJS: - - -the concatenation of $(HS_OBJS) and $(C_OBJS). - - - - - - -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 on the file's suffix (e.g. .hs, .lhs, .c, .lc, etc), but -this is the kind of detail that changes, so rather than -enumerate the source suffices here the best thing to do is to look in -paths.mk. - - - -opts.mkopts.mk - - -defines make variables for option -strings to pass to each program. For example, it defines -HC_OPTSHC_OPTS, the option strings to pass to the Haskell -compiler. See . - - - -suffix.mksuffix.mk - - -defines standard pattern rules—see . - - - - - - -Any of the variables and pattern rules defined by the boilerplate file -can easily be overridden in any particular Makefile, because the -boilerplate include comes first. Definitions after this include -directive simply override the default ones in boilerplate.mk. - - - - - -Pattern rules and options - -<IndexTerm><Primary>Pattern rules</Primary></IndexTerm> - - -The file suffix.mksuffix.mk defines standard 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 -pattern rules are more powerful and easier to use than Unix -make's suffix rules.) - - - -Almost all the rules look something like this: - - - - - -%.o : %.c - $(RM) $@ - $(CC) $(CC_OPTS) -c $< -o $@ - - - - - -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 program's 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: - - - - - -CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) - - - - - -The four variables from which CC_OPTS is built have the following meaning: - - - - - - -SRC_CC_OPTSSRC_CC_OPTS: - - -options passed to all C -compilations. - - - -WAY_<way>_CC_OPTS: - - -options passed to C -compilations for way <way>. For example, -WAY_mp_CC_OPTS gives options to pass to the C compiler when -compiling way mp. The variable WAY_CC_OPTS holds -options to pass to the C compiler when compiling the standard way. -( dicusses multi-way -compilation.) - - - -<module>_CC_OPTS: - - -options to -pass to the C compiler that are specific to module <module>. For example, SMap_CC_OPTS gives the specific options -to pass to the C compiler when compiling SMap.c. - - - -EXTRA_CC_OPTSEXTRA_CC_OPTS: - - -extra options to pass to all -C compilations. This is intended for command line use, thus: - - - - - -gmake libHS.a EXTRA_CC_OPTS="-v" - - - - - - - - - - -The main <Filename>mk/target.mk</Filename> file - -<IndexTerm><Primary>target.mk</Primary></IndexTerm> - - -target.mk contains canned rules for all the standard targets -described in . 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 weird -special cases yourself. - - - - - - -HS_PROGHS_PROG. - - -If HS_PROG is defined, you get -rules with the following targets: - - - -HS_PROGHS_PROG - - -itself. This rule links $(OBJS) -with the Haskell runtime system to get an executable called -$(HS_PROG). - - - -installinstall - - -installs $(HS_PROG) -in $(bindir). - - - - - - -C_PROGC_PROG - - -is similar to HS_PROG, except that -the link step links $(C_OBJS) with the C runtime system. - - - -LIBRARYLIBRARY - - -is similar to HS_PROG, except that -it links $(LIB_OBJS) to make the library archive $(LIBRARY), and -install installs it in $(libdir). - - - -LIB_DATALIB_DATA - - -… - - - -LIB_EXECLIB_EXEC - - -… - - - -HS_SRCSHS_SRCS, C_SRCSC_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. - - - - - - -All of these rules are ``double-colon'' rules, thus - - - - - -install :: $(HS_PROG) - ...how to install it... - - - - - -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. - - - - - -Recursion - -<IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm> -<IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm> - - -In leaf Makefiles the variable SUBDIRSSUBDIRS is undefined. -In non-leaf Makefiles, SUBDIRS is set to the list of -sub-directories that contain subordinate Makefiles. It is up to -you to set SUBDIRS in the Makefile. There is no automation here—SUBDIRS is too important to automate. - - - -When SUBDIRS is defined, target.mk includes a rather -neat rule for the standard targets ( that simply invokes -make recursively in each of the sub-directories. - - - -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. - - - - - -Way management - -<IndexTerm><Primary>way management</Primary></IndexTerm> - - -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.mktarget.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 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. 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: - - - - - - - - - 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 (). - -It is up to you to set WAYS in your Makefile; this is how you -control what ways will get built. - - - - - - 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 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: - - - -%.$(way_)o : %.lhs - $(HC) $(HC_OPTS) $< -o $@ - - - -Neat, eh? - - - - - - - - - - -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 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. - - - - - - - -Booting/porting from C (<Filename>.hc</Filename>) files - -<IndexTerm><Primary>building GHC from .hc files</Primary></IndexTerm> -<IndexTerm><Primary>booting GHC from .hc files</Primary></IndexTerm> -<IndexTerm><Primary>porting GHC</Primary></IndexTerm> - - -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 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 for setting -up a build tree. When you invoke the configure script, you'll have -to tell the script about your intentions: - - - - - -foo% ./configure --enable-hc-boot - - ---enable-hc-boot ---disable-hc-boot - - - -Assuming it configures OK and you don't need to create mk/build.mk -for any other purposes, the next step is to proceed with a make boot -followed by make all. At the successful completion of make all, -you should end up with a binary of the compiler proper, -ghc/compiler/hsc, plus archives (but no .hi files!) of the prelude -libraries. To generate the Prelude interface files (and test drive the -bootstrapped compiler), re-run the configure script, but this time -without the option. After that re-create the -contents of ghc/lib: - - - - - -foo% ./configure - .... -foo% cd ghc/lib -foo% make clean -foo% make boot -foo% 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.) - - - - - -Known pitfalls in building Glasgow Haskell - -<IndexTerm><Primary>problems, building</Primary></IndexTerm> -<IndexTerm><Primary>pitfalls, in building</Primary></IndexTerm> -<IndexTerm><Primary>building pitfalls</Primary></IndexTerm> - - -WARNINGS about pitfalls and known ``problems'': - - - - - - - - -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 to temp -space.) -tmp, running out of space in - -The quickest way around it is setenv TMPDIR /usr/tmpTMPDIR or -even setenv TMPDIR . (or the equivalent incantation with your shell -of choice). - -The best way around it is to say - - -export TMPDIR=<dir> - - -in your build.mk file. -Then GHC and the other fptools programs will use the appropriate directory -in all cases. - - - - - - - -In compiling some support-code bits, e.g., in ghc/rts/gmp and even -in ghc/lib, you may get a few C-compiler warnings. We think these -are OK. - - - - - - -When compiling via C, you'll sometimes get ``warning: assignment from -incompatible pointer type'' out of GCC. Harmless. - - - - - - -Similarly, archiving warning messages like the following are not -a problem: - - -ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ -ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ -... - - - - - - - - - In compiling the compiler proper (in compiler/), you may -get an ``Out of heap space'' error message. These can vary with the -vagaries of different systems, it seems. The solution is simple: - - - - - - - If you're compiling with GHC 4.00 or above, then the -maximum heap size must have been reached. This is somewhat -unlikely, since the maximum is set to 64M by default. Anyway, you can -raise it with the flag (add this flag to -<module>_HC_OPTS make variable in the appropriate Makefile). - - - - - - - For GHC < 4.00, add a suitable flag to the Makefile, as -above. - - - - - - - -and try again: gmake. (see for information about -<module>_HC_OPTS.) - -Alternatively, just cut to the chase: - - -% cd ghc/compiler -% make EXTRA_HC_OPTS=-optCrts-M128M - - - - - - - - -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. - - - - - - - -You may need to re-ranlibranlib your libraries (on Sun4s). - - - -% 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 - - - -We'd be interested to know if this is still necessary. - - - - - - - -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: - - - -SLIT("Hello, world") - - - -Some cpps treat the comma inside the string as separating two macro -arguments, so you get - - - -:731: macro `SLIT' used with too many (2) args - - - -Alas, cpp doesn't tell you the offending file! - -Workaround: don't put weird things in string args to cpp macros. - - - - - - - - - - -Notes for building under Windows - - -This section summarises how to get the utilities you need on your -Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. It is based largely on detailed advice from Sigbjørn Finne. - - - -Installing ssh - - - - - -Extract the whole of the ssh archive into your C:\ directory, and use the ``All files'' and ``User folder names'' options in WinZip extract dialogue box. This populates your C:\usr\local tree. - - - - - -Extract cygwinb19.dll into /usr/local/bin. The current version -of Cywin is b20, but this version of ssh was compiled with b19. - - - - - -On a Win2k machine, open up a bash and do - - - -foo$ cd /etc -foo$ mkpasswd -l > passwd - - - -Check that your login entry is on the first line -of that file. If not, move it to the top. It's OK -for 'Administrator' to be the first entry, assuming you are one. - - - -However, Win9x doesn't support the calls that mkpasswd relies on -(e.g., NetUserEnum). If you run mkpasswd you -get errors like: - - - -linked to missing export netapi32.dll:NetUserEnum - - - -The passwd file is used -by ssh in a fairly rudimentary manner, so I'd simply -synthesise/copy an existing Unix /etc/passwd, i.e., create -an /etc/passwd file containing the line - - - -<login>::500:513:::/bin/sh - - - -where <login> is your login id. - - - - - -Generate a key, by running c:/user/local/bin/ssh-keygen1. - This generates a public key in .ssh/identity.pub, and a - private key in .ssh/identity - - - - In response to the 'Enter passphrase' question, just hit - return (i.e. use an empty passphrase). The passphrase is - a password that protects your private key. But it's a pain - to type this passphrase everytime you use ssh, so the best - thing to do is simply to protect your .ssh directory, and - .ssh/identity from access by anyone else. To do this - right-click your .ssh directory, and select Properties. - If you are not on the access control list, add yourself, and - give yourself full permissions (the second panel). - Remove everyone else from the access control list. (Don't - leave them there but deny them access, because 'they' may be - a list that includes you!) - - - - If you have problems running ssh-keygen1 - from within bash, start up cmd.exe and run it as follows: - - - -c:\tmp> set CYGWIN32=tty -c:\tmp> c:/user/local/bin/ssh-keygen1 - - - - - -If you don't have an account on cvs.haskell.org, send - your .ssh/identity.pub to the CVS repository administrator - (currently Jeff Lewis jlewis@cse.ogi.edu). He will set up - your account. - - - - If you do have an account on cvs.haskell.org, use TeraTerm - to logon to it. Once in, copy the - key that ssh-keygen1 deposited in /.ssh/identity.pub into - your ~/.ssh/authorized_keys. Make sure that the new version - of authorized_keys still has 600 file permission. - - - - - - - - -Installing CVS - - - - - -Unpack - -CVS and, following the instructions in the README, copy the -appropriate files into /usr/local/bin. - - - - - -From the System control panel, -set the following user environment variables (see the GHC user guide) - - - - - -HOME: points to your home directory. This is where CVS -will look for its .cvsrc file. - - - - - -CVS_RSH: c:/usr/local/bin/ssh1 - - - - - -CVSROOT: :ext:username@cvs.haskell.org:/home/cvs/root, -where username is your userid - - - - - -CVSEDITOR: bin/gnuclient.exe if you want to use an Emacs buffer for typing in those long commit messages. - - - - - - - -Put the following in $HOME/.cvsrc: - - - -checkout -P -release -d -update -P -diff -u - - - -These are the default options for the specified CVS commands, -and represent better defaults than the usual ones. (Feel -free to change them.) - - - -Filenames starting with "." were illegal in -the 8.3 DOS filesystem, but that restriction should have -been lifted by now (i.e., you're using VFAT or later filesystems.) If -you're still having problems creating it, don't worry; .cvsrc is entirely -optional. - - - - - -Try doing cvs co fpconfig. All being well, bytes should -start to trickle through, leaving a directory fptools -in your current directory. (You can rm it if you don't want to keep it.) The following messages appear to be harmless: - - - -setsockopt IPTOS_LOWDELAY: Invalid argument -setsockopt IPTOS_THROUGHPUT: Invalid argument - - - -At this point I found that CVS tried to invoke a little dialogue with -me (along the lines of `do you want to talk to this host'), but -somehow bombed out. This was from a bash shell running in emacs. -I solved this by invoking a Cygnus shell, and running CVS from there. -Once things are dialogue free, it seems to work OK from within emacs. - - - - - -If you want to check out part of large tree, proceed as follows: - - - -cvs -f checkout -l papers -cd papers -cvs update cpr - - - -This sequence checks out the papers module, but none -of its sub-directories. -The "" flag says not to check out sub-directories. -The "" flag says not to read the .cvsrc file -whose default (don't check out empty directories) is -in this case bogus. - - - -The cvs update command sucks in a named sub-directory. - - - - - - -There is a very nice graphical front-end to CVS for Win32 platforms, -with a UI that people will be familiar with, at -wincvs.org. -I have not tried it yet. - - - - - -Installing autoconf - - -Only required if you are doing builds from GHC's sources -checked out from the CVS tree. - - - - - -Fetch the (standard, Unix) autoconf distribution from -ftp.gnu.org. - - - - -Unpack it into an arbitrary directory. - - - - -Make sure that the directory /usr/local/bin exists. - - - - -Say "./configure". - - - - -Now make install. This should put autoheader -and autoconf in /usr/local/bin. - - - - - -autoheader doesn't seem to work, but you don't need it -for GHC. - - - - - -Building GHC - - - - - -In the ./configure output, ignore -" -checking whether #! works in shell scripts... -./configure: ./conftest: No such file or directory", -and "not updating unwritable cache ./config.cache". -Nobody knows why these happen, but they seem to be harmless. - - - - - -You have to run autoconf both in fptools -and in fptools/ghc. If you omit the latter step you'll -get an error when you run ./configure: - - - -...lots of stuff... -creating mk/config.h -mk/config.h is unchanged -configuring in ghc -running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. -./configure: ./configure: No such file or directory -configure: error: ./configure failed for ghc - - - - - -You need ghc to be in your PATH before you run -configure. The default GHC InstallShield creates only -ghc-4.05, so you may need to duplicate this file as ghc -in the same directory, in order that configure will see it (or -just rename ghc-4.05 to ghc. -And make sure that the directory is in your path. - - - - - -Compile happy and ghc -with . To do this, set - - - -GhcHcOpts=-static -HappyHcOpts=-static - - - -in your build.mk file. -[Actually, I successfully compiled Happy without on Win2k, but not GHC.] - - - - - - - - - -
-- 1.7.10.4