X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding.sgml;h=c40bb8cdd08523462f7e817077c1bc2ec3dd9e5e;hb=0575839997b542eb43d4908abffa3e5c850e652b;hp=0ed4bd99d480b611ce60913b26be44ec288e5812;hpb=191991d16a295b70283820476cbb65b9f3eea1c1;p=ghc-hetmet.git diff --git a/docs/building.sgml b/docs/building.sgml index 0ed4bd9..c40bb8c 100644 --- a/docs/building.sgml +++ b/docs/building.sgml @@ -4,9 +4,9 @@ -Building and Installing the Glasgow Functional Programming Tools Suite +Building the Glasgow Functional Programming Tools Suite The GHC Team -
glasgow-haskell-{users,bugs}@dcs.gla.ac.uk
+
glasgow-haskell-{users,bugs}@haskell.org
January 2000 @@ -105,7 +105,8 @@ 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. +Source releases of GHC 4.xx can be compiled up using GHC 2.10 or +later. @@ -155,10 +156,9 @@ derived files from scratch. -More information about our CVS repository is available at The Fptools CVS Cheat Sheet. +More information about our CVS repository is available in the FPTools CVS +Cheat Sheet. @@ -201,15 +201,12 @@ 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. +SPARC boxes, and PCs running Linux, FreeBSD, NetBSD, or Solaris are +all fully supported. Win32 and HP boxes are in pretty good shape. +DEC Alphas running OSF/1, Linux or some BSD variant, MIPS and AIX +boxes will need some minimal porting effort before they work (as of +4.06). gives the full run-down on +ports or lack thereof. @@ -225,20 +222,24 @@ and/or porting expertise. If you have any problem when building or installing the Glasgow -tools, please check the ``known pitfalls'' (). Also check the known bugs page. +tools, please check the ``known pitfalls'' (). Also check the FAQ for the version +you're building, which should be available from the relevant download +page on the GHC web +site. + 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 +For GHC, please see the bug-reporting section of the GHC Users' 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. +If in doubt, please send a message to +glasgow-haskell-bugs@haskell.org. bugs, mailing list @@ -297,243 +298,148 @@ port; (c) the bare minimum is an ``unregisterised'' port. -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. +The native code generator is currently non-functional (as of GHC +version 4.06), but we're actively working on getting it going again. -Here's everything that's known about GHC ports. We identify platforms -by their ``canonical'' CPU/Manufacturer/OS triple. +We use Sparcs running Solaris 2.7 and x86 boxes running FreeBSD and +Linux, so those are the best supported platforms, unsurprisingly. -Note that some ports are fussy about which GCC version you use; or -require GAS; or… +Here's everything that's known about GHC ports. We identify platforms +by their ``canonical'' CPU/Manufacturer/OS triple. -alpha-dec-osf1: +alpha-dec-{osf,linux,freebsd,openbsd,netbsd}: +alpha-dec-osf +alpha-dec-linux +alpha-dec-freebsd +alpha-dec-openbsd +alpha-dec-netbsd - -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. +Currently non-working. The last working version (osf[1-3]) is GHC +3.02. A small amount of porting effort will be required to get Alpha +support into GHC 4.xx, but we don't have easy access to machines right +now, and there hasn't been a massive demand for support, so Alphas +remain unsupported for the time being. Please get in touch if you +either need Alpha support and/or can provide access to boxes. + sparc-sun-sunos4: +sparc-sun-sunos4 - -sparc-sun-sunos4: fully supported - -Fully supported, including native-code generator. +Probably works with minor tweaks, hasn't been tested for a while. + sparc-sun-solaris2: +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). +Fully supported, including native-code generator. + -HP-PA box running HP +hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x) +hppa1.1-hp-hpux - -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. +Works registerised. No native-code generator. - -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-unknown-linux (PCs running Linux—ELF binary format): +i386-*-linux - -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 +GHC works registerised. You must have GCC 2.7.x +or later. NOTE about glibc versions: GHC binaries +built on a system running glibc 2.0 won't work on a +system running glibc 2.1, and vice version. In +general, don't expect compatibility between glibc +versions, even if the shared library version hasn't changed. - -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-unknown-{freebsd,netbsd,openbsd) (PCs running FreeBSD 2.2 +or higher, NetBSD, and possibly OpenBSD): +i386-unknown-freebsd +i386-unknown-netbsd +i386-unknown-openbsd - -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 +GHC works registerised. These systems provide ready-built packages of +GHC, so if you just need binaries you're better off just installing +the package. + i386-unknown-cygwin32: +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. +Fully supported under Win9x/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.). - -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): +mips-sgi-irix5: +mips-sgi-irix[5-6] - -m68k-apple-macos7: historically ported -Once upon a time, David Wright in Tasmania actually -got 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. +Port currently doesn't work, needs some minimal porting effort. As +usual, we don't have access to machines and there hasn't been an +overwhelming demand for this port, but feel free to get in touch. - -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): +powerpc-ibm-aix: -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 +powerpc-ibm-aix +Port currently doesn't work, needs some minimal porting effort. As +usual, we don't have access to machines and there hasn't been an +overwhelming demand for this port, but feel free to get in touch. + + +Various other systems have had GHC ported to them in the distant past, +including various Motorola 68k boxes. The 68k support still remains, +but porting to one of these systems will certainly be a non-trivial +task. + + @@ -543,11 +449,6 @@ Concurrent/Parallel Haskell probably don't work (yet). Unless you hear otherwise, the other tools work if GHC works. - -Haggis requires Concurrent Haskell to work. -Haggis, Concurrent Haskell - - @@ -561,8 +462,11 @@ Haggis requires Concurrent Haskell to work. 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 +perl, gcc and +happy 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. @@ -571,39 +475,44 @@ 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. + + +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 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. +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! +We recommend using GCC version 2.95.2 on all platforms. Failing that, +version 2.7.2 is stable on most platforms. Earlier versions of GCC +can be assumed not to work, and versions in between 2.7.2 and 2.95.2 +(including egcs) have varying degrees of stability +depending on the platform. @@ -613,72 +522,64 @@ please let us know, so we can report it and get things improved. 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. - + +Happy: +Happy + +Happy is a parser generator tool for Haskell, and is used to +generate GHC's parsers. Happy is written in Haskell, and is a project +in the CVS repository (fptools/happy). It can be +built from source, but bear in mind that you'll need GHC installed in +order to build it. To avoid the chicken/egg problem, install a binary +distribtion of either Happy or GHC to get started. Happy +distributions are available from Happy's Web Page. + + + - -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. +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. +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.) + + +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. +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. @@ -690,11 +591,9 @@ Like lndir for creating symbolic link trees. 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 @@ -706,8 +605,8 @@ 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. +available on the net; I think I got it from +research.att.com, in netlib. @@ -717,9 +616,9 @@ the Readme instructions. bash: +bash, presupposed (Parallel Haskell only) -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). @@ -744,22 +643,30 @@ 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). + + +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. You need all the RPMs except for psgml (i.e. docbook, jade, +jadetex, sgmlcommon and stylesheets). Unfortunately, it's only packaged as +RPMs. You can use it to generate HTML, DVI (and hence PDF and Postscript) +and RTF from any DocBook source file (including this manual). N.B. The +Cygnus version of the tools is assumed. Others, such as +the SuSE version, may not work. Note that most of these RPMs are +architecture neutral, so are likely to be found in a noarch +directory. 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. @@ -774,26 +681,21 @@ 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. +of utilities in glafp-utils. Depending on your +operating system, the supplied lex may or may not +work; you should get the GNU version. - @@ -920,10 +822,11 @@ 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. +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. @@ -997,6 +900,13 @@ no arguments). This GNU program converts $(FPTOOLS&lo to a shell script called $(FPTOOLS_TOP)/configure. + +Some projects, including GHC, have their own configure script. If +there's an +$(FPTOOLS_TOP)/<project>/configure.in, +then you need to run autoconf in that directory too. + + Both these steps are completely platform-independent; they just mean that the human-written file (configure.in) can be short, although @@ -1020,12 +930,13 @@ 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: +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: @@ -1351,8 +1262,12 @@ file. Typing gmake alone is generally the same as typing 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. +install them? That is specified by +mk/config.mk.in; you can override it in +mk/build.mk, or by running +configure with command-line arguments like +--bindir=/home/simonpj/bin; see ./configure +--help for the full details. @@ -1362,23 +1277,56 @@ override it in mk/build.mk. reverses the effect of install. + clean: -remove all easily-rebuilt files. - +Delete all files from the current directory that are normally +created by building the program. Don't delete the files that +record the configuration. Also preserve files that could be made +by building, but normally aren't because the distribution comes +with them. + + +distclean: + +Delete all files from the current directory that are created by +configuring or building the program. If you have unpacked the source +and built the program without creating any other files, make +distclean should leave only the files that were in the +distribution. + + + + +mostlyclean: + +Like clean, but may refrain from deleting a +few files that people normally don't want to recompile. + + + -veryclean: +maintainer-clean: -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). - - +Delete everything from the current directory that can be reconstructed +with this Makefile. This typically includes everything deleted by +distclean, plus more: C source files produced by +Bison, tags tables, Info files, and so on. + +One exception, however: make maintainer-clean +should not delete configure even if +configure can be remade using a rule in the +Makefile. More generally, make +maintainer-clean should not delete anything that needs to +exist in order to run configure and then begin to +build the program. + + + check: @@ -1455,11 +1403,33 @@ Most Makefiles have targets other than these. You can disc + +Using a project from the build tree + +If you want to build GHC (say) and just use it direct from the build +tree without doing make install first, you can run +the in-place driver script: +ghc/driver/ghc-inplace. + + + Do NOT use +ghc/driver/ghc, or +ghc/driver/ghc-4.xx, as these are the scripts +intended for installation, and contain hard-wired paths to the +installed libraries, rather than the libraries in the build tree. + + + +Happy can similarly be run from the build tree, using +happy/src/happy-inplace. + + + -Fast Making -<IndexTerm><Primary>fastmake</Primary></IndexTerm> +<Title>Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm> <IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm> -<IndexTerm><Primary>FAST, makefile variable</Primary></IndexTerm> +FAST, makefile +variable Sometimes the dependencies get in the way: if you've made a small @@ -2578,11 +2548,14 @@ 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). + If you're compiling with GHC 4.00 or later, 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).