[[project @ 2002-05-02 14:37:27 by simonmar] simonmar**20020502143727 Overhaul: - Fix the markup in various ways, and indent it so it doesn't look so much like it was machine-generated by a badly written perl script - Add a section entitled "Porting GHC", describing the intricacies of porting from unregisterised .hc files, amongst other things. Comments/corrections welcome. ] { hunk ./docs/building/building.sgml 33 - Getting the Glasgow <Literal>fptools</Literal> suite + Getting the sources + + You can get your hands on the fptools + in two ways: hunk ./docs/building/building.sgml 38 - 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 distributionBinary 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 distributionSource 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. - + hunk ./docs/building/building.sgml 40 - -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 -happyhappy -you'll find it convenient that the source distribution contains the -result of running happy on the parser -specifications. If you don't want to alter the parser then this saves -you having to find and install happy. You will -still need a working version of GHC (preferably version 4.08+) on your -machine in order to compile (most of) the sources, however. - + + Source + distributionsSource distributions + + 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. hunk ./docs/building/building.sgml 50 - + 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 + happyhappy + you'll find it convenient that the source distribution + contains the result of running happy on + the parser specifications. If you don't want to alter the + parser then this saves you having to find and install + happy. You will still need a working + version of GHC (preferably version 4.08+) on your machine in + order to compile (most of) the sources, however. + + hunk ./docs/building/building.sgml 75 - All the fptools source code is held + All the fptools source code is held hunk ./docs/building/building.sgml 88 - - - - - - Build GHC from intermediate C .hc fileshc files: - - NOTE: GHC version 5.xx is significantly - harder to bootstrap from C than previous versions. We - recommend starting from version 4.08.2 if you need to - bootstrap in this way. - - You need a working GHC to use a source distribution. - What if you don't have a working GHC? Then you may be able - to bootstrap up from the intermediate C - (.hc) files that we provide. Building - GHC on an unsupported platform falls into this category. - Beware: this route is not for the faint hearted! 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). hunk ./docs/building/building.sgml 325 - set this to point to bash.exe. + set this to point to bash.exe. hunk ./docs/building/building.sgml 758 + + haddock + haddockproject + + The Haddock + documentation tool. + + + hunk ./docs/building/building.sgml 801 - GHC's libraries. Required for building GHC. + Supplemental libraries for GHC + (required for building GHC). hunk ./docs/building/building.sgml 811 - (experimental). + (required for building GHC). hunk ./docs/building/building.sgml 843 - ghc and hslibs projects (a - GHC source distribution will already include the bits you - need). + ghc, libraries and + hslibs projects (a GHC source distribution will + already include the bits you need). hunk ./docs/building/building.sgml 865 - Use an appropriate machine, compilers, and things. - SPARC boxes, PCs running Linux or FreeBSD, and Alphas running - OSF/1 are all fully supported. Win32 and HP boxes are in - pretty good shape. PCs running Solaris, DEC Alphas running - 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. + Use an appropriate machine / operating system. lists the supported platforms; if + yours isn't amongst these then you can try porting GHC (see + ). hunk ./docs/building/building.sgml 872 - Be sure that the ``pre-supposed'' utilities are + Be sure that the “pre-supposed” utilities are hunk ./docs/building/building.sgml 879 - Glasgow tools, please check the ``known pitfalls'' (GHC web - site. + version you're building, which is part of the User's Guide and + available on the GHC web + site. hunk ./docs/building/building.sgml 885 - known bugs - bugs, known + bugsknown hunk ./docs/building/building.sgml 890 - For GHC, please see the bug-reporting section of the GHC - Users' Guide (separate document), to maximise the usefulness - of your report. + For GHC, please see the bug-reporting + section of the GHC Users' Guide, to maximise the + usefulness of your report. hunk ./docs/building/building.sgml 896 - hunk ./docs/building/building.sgml 897 -glasgow-haskell-bugs@haskell.org. -bugsmailing -list - + glasgow-haskell-bugs@haskell.org. + bugsmailing + list hunk ./docs/building/building.sgml 904 - -What machines the Glasgow tools run on - + + What machines the Glasgow tools run on hunk ./docs/building/building.sgml 907 - -ports, GHC -GHC ports -supported platforms -platforms, supported -The main question is whether or not the Haskell compiler (GHC) runs on -your platform. - +portsGHC +GHCports +platformssupported hunk ./docs/building/building.sgml 911 - -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. - + The main question is whether or not the Haskell compiler + (GHC) runs on your platform. hunk ./docs/building/building.sgml 914 - -Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not -work on all machines for which basic Haskell compiling is supported. - + 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. hunk ./docs/building/building.sgml 929 - -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. - + 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. hunk ./docs/building/building.sgml 933 - -What platforms the Haskell compiler (GHC) runs on + + What platforms the Haskell compiler (GHC) runs on hunk ./docs/building/building.sgml 936 - -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). - + fully-supported platforms + native-code generator + registerised ports + unregisterised ports hunk ./docs/building/building.sgml 941 - -We use Sparcs running Solaris 2.7 and x86 boxes running FreeBSD and -Linux, so those are the best supported platforms, unsurprisingly. - + 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). hunk ./docs/building/building.sgml 948 - -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. hunk ./docs/building/building.sgml 952 - + Here's everything that's known about GHC ports. We + identify platforms by their “canonical” + CPU/Manufacturer/OS triple. hunk ./docs/building/building.sgml 956 + hunk ./docs/building/building.sgml 986 - Fully supported, including native-code - generator. + Fully supported (at least for Solaris 2.7), + including native-code generator. hunk ./docs/building/building.sgml 995 - Works registerised. No native-code - generator. + A registerised port is available for version 4.08, + but GHC hasn't been built on that platform since (as far + as we know). No native-code generator. hunk ./docs/building/building.sgml 1018 - i386-unknown-freebsd (PCs running FreeBSD 2.2 -or higher) + i386-unknown-freebsd (PCs running FreeBSD 2.2 or + higher) hunk ./docs/building/building.sgml 1025 - package. + package (it might even be on your installation + CD!). hunk ./docs/building/building.sgml 1029 - + hunk ./docs/building/building.sgml 1031 - i386-unknown-{netbsd,openbsd) (PCs running NetBSD - and OpenBSD) - i386-unknown-netbsd + i386-unknown-openbsd (PCs running OpenBSD) hunk ./docs/building/building.sgml 1034 + Supported, with native code generator. Packages are + available through the ports system in the native package + format. + + + + + i386-unknown-netbsd (PCs running NetBSD and + OpenBSD) + i386-unknown-netbsd + hunk ./docs/building/building.sgml 1051 - i386-unknown-mingw32: + i386-unknown-mingw32 (PCs running Windows) hunk ./docs/building/building.sgml 1056 - source requires a recent cygwin32 - distribution to be installed. + source requires a recent Cygwin distribution + to be installed. hunk ./docs/building/building.sgml 1066 - 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. + Port has worked in the past, but hasn't been tested + for some time (and will certainly have rotted in various + ways). 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. hunk ./docs/building/building.sgml 1089 - Works, unregisterised only at the moment. + Supported registerised. No native code + generator. + + + + + powerpc-apple-linux + powerpc-apple-linux + + Not supported (yet). hunk ./docs/building/building.sgml 1118 - -Installing pre-supposed utilities + <sect1 id="sec-pre-supposed"> + <title>Installing pre-supposed utilities hunk ./docs/building/building.sgml 1121 -pre-supposed utilities -utilities, pre-supposed + pre-supposed utilities + utilities, pre-supposed hunk ./docs/building/building.sgml 1124 - -Here are the gory details about some utility programs you may need; -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. - + Here are the gory details about some utility programs you + may need; 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. hunk ./docs/building/building.sgml 1132 - - - - -Perl: -pre-supposed: Perl -Perl, pre-supposed - - -You have to have Perl to proceed! Perl version 5 -at least is required. GHC has been known to tickle bugs in Perl, so -if you find that Perl crashes when running GHC try updating (or -downgrading) your Perl installation. Versions of Perl that we use and -are known to be fairly stable are 5.005 and 5.6.1. - - - -For Win32 platforms, you should use the binary supplied in the -InstallShield (copy it to /bin). The -Cygwin-supplied Perl seems not to work. - - - -Perl should be put somewhere so that it can be invoked by the -#! script-invoking mechanism. The full -pathname 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 - - - -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. - - - -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) - - - - -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. - - - - - -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. - + hunk ./docs/building/building.sgml 1134 - -Tools for building parallel GHC (GPH) - + + Perl + pre-supposed: Perl + Perl, pre-supposed + + You have to have Perl to proceed! + Perl version 5 at least is required. GHC has been known to + tickle bugs in Perl, so if you find that Perl crashes when + running GHC try updating (or downgrading) your Perl + installation. Versions of Perl that we use and are known to + be fairly stable are 5.005 and 5.6.1. hunk ./docs/building/building.sgml 1146 - - + For Win32 platforms, you should use the binary + supplied in the InstallShield (copy it to + /bin). The Cygwin-supplied Perl seems + not to work. hunk ./docs/building/building.sgml 1151 - -PVM version 3: -pre-supposed: PVM3 (Parallel Virtual Machine) -PVM3 (Parallel Virtual Machine), pre-supposed - + Perl should be put somewhere so that it can be invoked + by the #! script-invoking + mechanism. The full pathname may need to be less than 32 + characters long on some systems. + + hunk ./docs/building/building.sgml 1158 - -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). - + + GNU C (gcc) + pre-supposed: GCC (GNU C + compiler) GCC (GNU C + compiler), pre-supposed + + 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. hunk ./docs/building/building.sgml 1171 - -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. - + 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) + + hunk ./docs/building/building.sgml 1180 - -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). - - - - + + GNU Make + makeGNU + + + The fptools build system makes heavy use of features + specific to GNU make, so you must have + this installed in order to build any of the fptools + suite. + + hunk ./docs/building/building.sgml 1192 - + + 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. + + hunk ./docs/building/building.sgml 1209 - -Tools for building the Documentation - + + 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. hunk ./docs/building/building.sgml 1218 - -The following additional tools are required if you want to format the -documentation that comes with the fptools projects: - + 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. + + hunk ./docs/building/building.sgml 1226 - - + + 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.) + + + hunk ./docs/building/building.sgml 1241 - -DocBook: -pre-supposed: DocBook -DocBook, pre-supposed - - -All our documentation is written in SGML, using the DocBook DTD. -Instructions on installing and configuring the DocBook tools are in the -installation guide (in the GHC user guide). - + 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. hunk ./docs/building/building.sgml 1248 - - -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. - - - - + + Tools for building parallel GHC (GPH) hunk ./docs/building/building.sgml 1251 - - In order to actually build any documentation, you need to set - SGMLDocWays in your - build.mk. Valid values to add to this - list are: dvi, ps, - pdf, html, and - rtf. - - - + + + 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). hunk ./docs/building/building.sgml 1265 - -Other useful tools - + 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. hunk ./docs/building/building.sgml 1270 - - -Flex: -pre-supposed: flex -flex, pre-supposed - + A PVM installation is slightly quirky, but easy to + do. Just follow the Readme + instructions. + + hunk ./docs/building/building.sgml 1276 - -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. - - - + + 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). + + + + hunk ./docs/building/building.sgml 1289 - + + Tools for building the Documentation hunk ./docs/building/building.sgml 1292 - + The following additional tools are required if you want to + format the documentation that comes with the + fptools projects: hunk ./docs/building/building.sgml 1296 - -Building from source + <variablelist> + <varlistentry> + <term>DocBook</term> + <indexterm><primary>pre-supposed: DocBook</primary></indexterm> + <indexterm><primary>DocBook, pre-supposed</primary></indexterm> + <listitem> + <para>All our documentation is written in SGML, using the + DocBook DTD. Instructions on installing and configuring + the DocBook tools are in the installation guide (in the + GHC user guide).</para> + </listitem> + </varlistentry> hunk ./docs/building/building.sgml 1309 -<indexterm><primary>Building from source</primary></indexterm> -<indexterm><primary>Source, building from</primary></indexterm> + + 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. + + + hunk ./docs/building/building.sgml 1321 - -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. - + In order to actually build any documentation, you need to + set SGMLDocWays in your + build.mk. Valid values to add to this list + are: dvi, ps, + pdf, html, and + rtf. + hunk ./docs/building/building.sgml 1329 - -Gingerly, you type make. Wrong already! - + + Other useful tools hunk ./docs/building/building.sgml 1332 - -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. - + + + 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. + + + + + hunk ./docs/building/building.sgml 1349 - -Your source tree - + + Building from source hunk ./docs/building/building.sgml 1352 - -The source code is held in your source tree. -The root directory of your source tree must -contain the following directories and files: - + Building from source + Source, building from hunk ./docs/building/building.sgml 1355 - + 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. hunk ./docs/building/building.sgml 1361 - - + Gingerly, you type make. Wrong + already! hunk ./docs/building/building.sgml 1364 - -Makefile: the root Makefile. - - - + 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. hunk ./docs/building/building.sgml 1371 - -mk/: the directory that contains the -main Makefile code, shared by all the -fptools software. - - - + + Your source tree hunk ./docs/building/building.sgml 1374 - - configure.in, config.sub, config.guess: -these files support the configuration process. - - - + The source code is held in your source + tree. The root directory of your source tree + must contain the following directories and + files: hunk ./docs/building/building.sgml 1379 - - install-sh. - - + + + Makefile: the root + Makefile. + hunk ./docs/building/building.sgml 1385 - + + mk/: the directory that contains + the main Makefile code, shared by all the + fptools software. + hunk ./docs/building/building.sgml 1391 - + + configure.in, + config.sub, + config.guess: these files support the + configuration process. + hunk ./docs/building/building.sgml 1398 - -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. - + + install-sh. + + hunk ./docs/building/building.sgml 1403 - -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. - + 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. hunk ./docs/building/building.sgml 1411 - + 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. + hunk ./docs/building/building.sgml 1420 - -Build trees -<indexterm><primary>build trees</primary></indexterm> -<indexterm><primary>link trees, for building</primary></indexterm> + + Build trees + build trees + link trees, for building hunk ./docs/building/building.sgml 1425 - -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. - + If you just want to build the software once on a single + platform, then your source tree can also be your build tree, and + you can skip the rest of this section. hunk ./docs/building/building.sgml 1429 - -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. - + 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. hunk ./docs/building/building.sgml 1434 - -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. - + 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. hunk ./docs/building/building.sgml 1449 - -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! - + 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. hunk ./docs/building/building.sgml 1462 - -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.) - + 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! hunk ./docs/building/building.sgml 1466 - -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. - + 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.) hunk ./docs/building/building.sgml 1482 - + 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. + hunk ./docs/building/building.sgml 1494 - -Getting the build you want - + + Getting the build you want hunk ./docs/building/building.sgml 1497 - -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. - + 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. hunk ./docs/building/building.sgml 1508 - -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. - + 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. hunk ./docs/building/building.sgml 1516 - -All of this stuff is called the configuration of your build. -You set the configuration using a three-step process. - + All of this stuff is called the + configuration of your build. You set the + configuration using a three-step process. hunk ./docs/building/building.sgml 1520 - -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. - + + + 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. + hunk ./docs/building/building.sgml 1534 - 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. + 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. hunk ./docs/building/building.sgml 1540 - 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. + 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. hunk ./docs/building/building.sgml 1547 - 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. - - + 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. + + hunk ./docs/building/building.sgml 1555 - - Step 2: system configuration. - - Runs the newly-created - configure script, thus: + + Step 2: system configuration. + + Runs the newly-created configure + script, thus: hunk ./docs/building/building.sgml 1565 - 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: hunk ./docs/building/building.sgml 1576 - 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. + + + + 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. hunk ./docs/building/building.sgml 1594 - - - configure takes some optional - arguments. Use ./configure --help to - get a list of the available arguments. Here are some of - the ones you might need: - - - - --with-ghc=path - --with-ghc - - - Specifies the path to an installed GHC which - you would like to use. This compiler will be used - for compiling GHC-specific code (eg. GHC itself). - This option cannot be - specified using build.mk (see - later), because configure needs - to auto-detect the version of GHC you're using. - The default is to look for a compiler named - ghc in your path. - - - - - --with-hc=path - --with-hc - - - Specifies the path to any installed Haskell - compiler. This compiler will be used for - compiling generic Haskell code. The default is to - use ghc. - - hunk ./docs/building/building.sgml 1595 - - --with-gcc=path - --with-gcc - - - Specifies the path to the installed - GCC. This compiler will be used to compile all C - files, except any generated - by the installed Haskell compiler, which will have - its own idea of which C compiler (if any) to use. - The default is to use gcc. - - - + + 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. + + hunk ./docs/building/building.sgml 1606 - 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. - - + configure takes some optional + arguments. Use ./configure --help to + get a list of the available arguments. Here are some of + the ones you might need: hunk ./docs/building/building.sgml 1611 - -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. - - - - + + + --with-ghc=path + --with-ghc + + + Specifies the path to an installed GHC which + you would like to use. This compiler will be used + for compiling GHC-specific code (eg. GHC itself). + This option cannot be specified + using build.mk (see later), + because configure needs to + auto-detect the version of GHC you're using. The + default is to look for a compiler named + ghc in your path. + + + + + --with-hc=path + --with-hc + + + Specifies the path to any installed Haskell + compiler. This compiler will be used for compiling + generic Haskell code. The default is to use + ghc. + + + + + --with-gcc=path + --with-gcc + + + Specifies the path to the installed GCC. This + compiler will be used to compile all C files, + except any generated by the + installed Haskell compiler, which will have its own + idea of which C compiler (if any) to use. The + default is to use gcc. + + + + + 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. + + + hunk ./docs/building/building.sgml 1687 - -And that's it for configuration. Simple, eh? - + And that's it for configuration. Simple, eh? hunk ./docs/building/building.sgml 1690 - mk/build.mk? For almost all + mk/build.mk? For almost all hunk ./docs/building/building.sgml 1692 - override those in + override those in hunk ./docs/building/building.sgml 1718 - + hunk ./docs/building/building.sgml 1725 - GNU make allows existing definitions to - have new text appended using the ``+='' + GNU make allows existing definitions to + have new text appended using the “+=” hunk ./docs/building/building.sgml 1739 - that anything between ``@...@'' signs is going to be substituted - by configure later. You - can override the resulting definition if + that anything between “@...@” signs is going to be substituted + by configure later. You + can override the resulting definition if hunk ./docs/building/building.sgml 1750 - to the pathname for a yacc that - configure finds somewhere. If you have your - own pet yacc you want to use instead, that's + to the pathname for a yacc that + configure finds somewhere. If you have your + own pet yacc you want to use instead, that's hunk ./docs/building/building.sgml 1759 - You do not have to have a + You do not have to have a hunk ./docs/building/building.sgml 1765 - anything that configure got wrong. One place + anything that configure got wrong. One place hunk ./docs/building/building.sgml 1771 - that configure has got it wrong, just put the + that configure has got it wrong, just put the hunk ./docs/building/building.sgml 1774 - + hunk ./docs/building/building.sgml 1794 - (Optional) Use lndir or - mkshadowdir to create a build tree. + (Optional) Use lndir or + mkshadowdir to create a build tree. hunk ./docs/building/building.sgml 1802 - (N.B. mkshadowdir's first argument + (N.B. mkshadowdir's first argument hunk ./docs/building/building.sgml 1868 - gmake clean, gmake all, + gmake clean, gmake all, hunk ./docs/building/building.sgml 1875 - Making things + Making things hunk ./docs/building/building.sgml 1881 - 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 + 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 hunk ./docs/building/building.sgml 1895 - + hunk ./docs/building/building.sgml 1897 - - Standard Targets + + Standard Targets hunk ./docs/building/building.sgml 1902 - In any directory you should be able to make the following: + In any directory you should be able to make the following: hunk ./docs/building/building.sgml 1904 - + + + 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. hunk ./docs/building/building.sgml 1914 - -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. + Invoking the boot target + explicitly is not normally necessary. From the top-level + fptools directory, invoking + gmake causes gmake boot + all to be invoked in each of the project + subdirectories, in the order specified by + $(AllTargets) in + config.mk. hunk ./docs/building/building.sgml 1923 -Invoking the boot target explicitly is not -normally necessary. From the top-level fptools -directory, invoking gmake causes gmake -boot all to be invoked in each of the project -subdirectories, in the order specified by -$(AllTargets) in -config.mk. + If you're working in a subdirectory somewhere and + need to update the dependencies, gmake + boot is a good way to do it. + + hunk ./docs/building/building.sgml 1929 -If you're working in a subdirectory somewhere and need to update -the dependencies, gmake boot is a good way to do it. + + 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. + + hunk ./docs/building/building.sgml 1941 - - -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 (except for the documentation). Where does it -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. - - - -install-docs: - - -installs the documentation. Otherwise behaves just like install. - - - -uninstall: - - -reverses the effect of install. - - + + install + + installs the things built by all + (except for the documentation). Where does it 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. + + hunk ./docs/building/building.sgml 1956 - -clean: - - -Delete all files from the current directory that are normally created -by building the program. Don't delete the files that record the -configuration, or files generated by gmake boot. -Also preserve files that could be made by building, but normally -aren't because the distribution comes with them. - + + install-docs + + installs the documentation. Otherwise behaves just + like install. + + hunk ./docs/building/building.sgml 1964 - -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. - - + + uninstall + + reverses the effect of + install. + + hunk ./docs/building/building.sgml 1972 - -mostlyclean: - -Like clean, but may refrain from deleting a -few files that people normally don't want to recompile. - - + + clean + + Delete all files from the current directory that are + normally created by building the program. Don't delete + the files that record the configuration, or files + generated by gmake boot. Also preserve + files that could be made by building, but normally aren't + because the distribution comes with them. + + hunk ./docs/building/building.sgml 1984 - -maintainer-clean: - - -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. + + 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. + + hunk ./docs/building/building.sgml 1996 -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. - - + + mostlyclean + + Like clean, but may refrain from + deleting a few files that people normally don't want to + recompile. + + hunk ./docs/building/building.sgml 2005 - -check: - - -run the test suite. - - - - + + maintainer-clean + + 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. hunk ./docs/building/building.sgml 2015 - -All of these standard targets automatically recurse into -sub-directories. Certain other standard targets do not: - + 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. + + hunk ./docs/building/building.sgml 2027 - - + + check + + run the test suite. + + + hunk ./docs/building/building.sgml 2035 - -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: - + All of these standard targets automatically recurse into + sub-directories. Certain other standard targets do not: hunk ./docs/building/building.sgml 2038 - + + + 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: hunk ./docs/building/building.sgml 2065 - + 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. + + hunk ./docs/building/building.sgml 2073 - -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. Note that this target does “make -distclean” as part of its work; don't use it if you want to keep -what you've built. - - - - + + binary-dist + + make a binary distribution. This is the target we + use to build the binary distributions of GHC and + Happy. + + hunk ./docs/building/building.sgml 2082 - -Most Makefiles have targets other than these. You can discover them by looking in the Makefile itself. - + + dist + + make a source distribution. Note that this target + does “make distclean” as part of its work; + don't use it if you want to keep what you've built. + + + hunk ./docs/building/building.sgml 2092 - + Most Makefiles have targets other + than these. You can discover them by looking in the + Makefile itself. + hunk ./docs/building/building.sgml 2097 - -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/compiler/ghc-inplace. - + + Using a project from the build tree hunk ./docs/building/building.sgml 2100 - Do NOT use -ghc/compiler/ghc, or -ghc/compiler/ghc-5.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. - + 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/compiler/ghc-inplace. hunk ./docs/building/building.sgml 2105 - -Happy can similarly be run from the build tree, using -happy/src/happy-inplace. - - + Do NOT use + ghc/compiler/ghc, or + ghc/compiler/ghc-5.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. hunk ./docs/building/building.sgml 2112 - -Fast Making <indexterm><primary>fastmake</primary></indexterm> -<indexterm><primary>dependencies, omitting</primary></indexterm> -<indexterm><primary>FAST, makefile -variable</primary></indexterm> + Happy can similarly be run from the build tree, using + happy/src/happy-inplace. + hunk ./docs/building/building.sgml 2116 - -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: - + + Fast Making hunk ./docs/building/building.sgml 2119 - + fastmake + dependencies, omitting + FAST, makefile variable + + 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: hunk ./docs/building/building.sgml 2133 - - - -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"). - - - + 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). hunk ./docs/building/building.sgml 2139 - + 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"). + + hunk ./docs/building/building.sgml 2148 - -The <filename>Makefile</filename> architecture -<indexterm><primary>makefile architecture</primary></indexterm> + + The <filename>Makefile</filename> architecture + makefile architecture hunk ./docs/building/building.sgml 2152 - -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. - + 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. hunk ./docs/building/building.sgml 2159 - -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. - + 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. hunk ./docs/building/building.sgml 2184 - -A small project + + A small project hunk ./docs/building/building.sgml 2187 - -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: - + 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: hunk ./docs/building/building.sgml 2198 - hunk ./docs/building/building.sgml 2212 - - - -This Makefile has three sections: - - - - - - - - - The first section includes - + this Makefile has three + sections: hunk ./docs/building/building.sgml 2215 + + + The first section includes + hunk ./docs/building/building.sgml 2221 -features of GNU make that we use is the ability for a Makefile to -include another named file, very like cpp's #include +features of GNU make that we use is the ability for a Makefile to +include another named file, very like cpp's #include hunk ./docs/building/building.sgml 2225 + hunk ./docs/building/building.sgml 2227 - - 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 + 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 hunk ./docs/building/building.sgml 2238 + 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 hunk ./docs/building/building.sgml 2250 -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. - - - - + 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. hunk ./docs/building/building.sgml 2265 - - 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.) + 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. + hunk ./docs/building/building.sgml 2277 - - - + + 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 . hunk ./docs/building/building.sgml 2288 - - It uses another standard pattern rule to compile Baz.c to -Baz.o, using a C compiler. (Ditto.) + 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.) + hunk ./docs/building/building.sgml 2300 - - - + + 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 . hunk ./docs/building/building.sgml 2312 - - 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.) + 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 (). + + hunk ./docs/building/building.sgml 2324 - - + In our example Makefile, most of the + work is done by the two included files. When + you say gmake all, the following things + happen: hunk ./docs/building/building.sgml 2329 - + + + gmake figures out that the object + files are Foo.o and + Baz.o. + hunk ./docs/building/building.sgml 2336 - + + 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.) + hunk ./docs/building/building.sgml 2343 - -All Makefiles should follow the above three-section format. - + + It uses another standard pattern rule to compile + Baz.c to Baz.o, + using a C compiler. (Ditto.) + hunk ./docs/building/building.sgml 2349 - + + 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.) + + hunk ./docs/building/building.sgml 2362 - -A larger project + All Makefiles should follow the above + three-section format. + hunk ./docs/building/building.sgml 2366 - -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: - + + A larger project hunk ./docs/building/building.sgml 2369 - + 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: hunk ./docs/building/building.sgml 2395 - + 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.) hunk ./docs/building/building.sgml 2413 - -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. hunk ./docs/building/building.sgml 2423 - -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: hunk ./docs/building/building.sgml 2428 - -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: - - - - - - + + + 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. + hunk ./docs/building/building.sgml 2438 - - boilerplate.mk consists of: + + 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. + + hunk ./docs/building/building.sgml 2448 - - + So these two files are the place to look for GHC-wide + customisation of the standard boilerplate. + hunk ./docs/building/building.sgml 2452 - - 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. - - - + + Boilerplate architecture + boilerplate architecture hunk ./docs/building/building.sgml 2456 - -Standard pattern rules that tell gmake how to construct one -file from another. - - + 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: hunk ./docs/building/building.sgml 2463 - + + + boilerplate.mk consists of: hunk ./docs/building/building.sgml 2467 + + + 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. + hunk ./docs/building/building.sgml 2482 -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. + + Standard pattern rules that + tell gmake how to construct one file + from another. + + hunk ./docs/building/building.sgml 2489 -Instead of replacing boilerplate definitions, it is also quite -common to augment them. For example, a Makefile might say: + 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. hunk ./docs/building/building.sgml 2497 + Instead of replacing boilerplate + definitions, it is also quite common to + augment them. For example, a + Makefile might say: hunk ./docs/building/building.sgml 2506 + thereby adding “” to + the end of + SRC_HC_OPTSSRC_HC_OPTS. + hunk ./docs/building/building.sgml 2511 -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: - + + 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. hunk ./docs/building/building.sgml 2521 - - + target.mk must be included at the + end (rather than being part of + boilerplate.mk) for several tiresome + reasons: hunk ./docs/building/building.sgml 2526 - - gmake commits target and dependency lists earlier than -it should. For example, target.mk has a rule that looks like -this: + + hunk ./docs/building/building.sgml 2529 + gmake commits target and + dependency lists earlier than it should. For example, + target.mk has a rule that looks + like this: hunk ./docs/building/building.sgml 2539 + 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. + hunk ./docs/building/building.sgml 2554 -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. - - - - - - - - - - - - - + + 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. + hunk ./docs/building/building.sgml 2564 - -The main <filename>mk/boilerplate.mk</filename> file + <listitem> + <para>There are a couple of other reasons I've + forgotten, but it doesn't matter too much.</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </sect2> hunk ./docs/building/building.sgml 2573 -<indexterm><primary>boilerplate.mk</primary></indexterm> + + The main <filename>mk/boilerplate.mk</filename> file + boilerplate.mk hunk ./docs/building/building.sgml 2577 - -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: - + 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: hunk ./docs/building/building.sgml 2583 - hunk ./docs/building/building.sgml 2596 - defines make variables for + defines make variables for hunk ./docs/building/building.sgml 2782 - defines make variables for option + defines make variables for option hunk ./docs/building/building.sgml 2800 - -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 + <para>Any of the variables and pattern rules defined by the + boilerplate file can easily be overridden in any particular + <filename>Makefile</filename>, because the boilerplate + <literal>include</literal> comes first. Definitions after this + <literal>include</literal> directive simply override the default + ones in <filename>boilerplate.mk</filename>.</para> + </sect2> hunk ./docs/building/building.sgml 2808 -<indexterm><primary>Pattern rules</primary></indexterm> + + Pattern rules and options + Pattern rules hunk ./docs/building/building.sgml 2812 - -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.) - + 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.) hunk ./docs/building/building.sgml 2822 - -Almost all the rules look something like this: - - - + Almost all the rules look something like this: hunk ./docs/building/building.sgml 2830 - + 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). hunk ./docs/building/building.sgml 2843 - -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). hunk ./docs/building/building.sgml 2849 - -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: - - - + 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: hunk ./docs/building/building.sgml 2860 - + The four variables from which + CC_OPTS is built have the following + meaning: hunk ./docs/building/building.sgml 2864 - -The four variables from which CC_OPTS is built have the following meaning: - + + + SRC_CC_OPTSSRC_CC_OPTS: + + options passed to all C compilations. + + hunk ./docs/building/building.sgml 2872 - - + + 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.) + + hunk ./docs/building/building.sgml 2887 - -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: - + + <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. + + hunk ./docs/building/building.sgml 2898 - + + EXTRA_CC_OPTSEXTRA_CC_OPTS: + + extra options to pass to all C compilations. This + is intended for command line use, thus: hunk ./docs/building/building.sgml 2907 + + + + hunk ./docs/building/building.sgml 2912 - - - - + + The main <filename>mk/target.mk</filename> file + target.mk hunk ./docs/building/building.sgml 2916 - + 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. hunk ./docs/building/building.sgml 2930 - -The main <filename>mk/target.mk</filename> file + <variablelist> + <varlistentry> + <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term> + <listitem> + <para>If <constant>HS_PROG</constant> is defined, + you get rules with the following targets:</para> hunk ./docs/building/building.sgml 2937 -<indexterm><primary>target.mk</primary></indexterm> + + + HS_PROGHS_PROG + + itself. This rule links + $(OBJS) with the Haskell + runtime system to get an executable called + $(HS_PROG). + + hunk ./docs/building/building.sgml 2948 - -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. - + + installinstall + + installs + $(HS_PROG) in + $(bindir). + + + hunk ./docs/building/building.sgml 2958 - - + + hunk ./docs/building/building.sgml 2961 - -HS_PROGHS_PROG. - - -If HS_PROG is defined, you get -rules with the following targets: - + + C_PROGC_PROG + + is similar to HS_PROG, + except that the link step links + $(C_OBJS) with the C + runtime system. + + hunk ./docs/building/building.sgml 2971 - -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. - - - - + + LIBRARYLIBRARY + + is similar to HS_PROG, + except that it links + $(LIB_OBJS) to make the + library archive $(LIBRARY), + and install installs it in + $(libdir). + + hunk ./docs/building/building.sgml 2983 - -All of these rules are ``double-colon'' rules, thus - + + LIB_DATALIB_DATA + + … + + hunk ./docs/building/building.sgml 2990 - + + 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 hunk ./docs/building/building.sgml 3017 - - - -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. - - - + 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. + hunk ./docs/building/building.sgml 3028 - -Recursion + <sect2 id="sec-subdirs"> + <title>Recursion + recursion, in makefiles + Makefile, recursing into subdirectories hunk ./docs/building/building.sgml 3033 -recursion, in makefiles -Makefile, recursing into subdirectories + 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. hunk ./docs/building/building.sgml 3044 - -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. hunk ./docs/building/building.sgml 3050 - -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. - - - + 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. + hunk ./docs/building/building.sgml 3066 - several different ``ways''. For example, we want to build GHC's + several different “ways”. For example, we want to build GHC's hunk ./docs/building/building.sgml 3070 - to have a completely separate build tree for each such ``way'', + to have a completely separate build tree for each such “way”, hunk ./docs/building/building.sgml 3096 - A make variable called + A make variable called hunk ./docs/building/building.sgml 3099 - command line of gmake (usually in + command line of gmake (usually in hunk ./docs/building/building.sgml 3103 - any one invocation of gmake. Two other - make variables, + any one invocation of gmake. Two other + make variables, hunk ./docs/building/building.sgml 3111 - make will build the normal + make will build the normal hunk ./docs/building/building.sgml 3114 - $(way) is ``mp'', + $(way) is “mp”, hunk ./docs/building/building.sgml 3116 - ``mp_'' and + “mp_” and hunk ./docs/building/building.sgml 3118 - ``_mp''. These three variables are + “_mp”. These three variables are hunk ./docs/building/building.sgml 3121 - So how does make ever get recursively + So how does make ever get recursively hunk ./docs/building/building.sgml 3128 - in a leaf sub-directory, make is + in a leaf sub-directory, make is hunk ./docs/building/building.sgml 3135 - make in sub-directories (make in sub-directories (make to make the + recursively invokes make to make the hunk ./docs/building/building.sgml 3148 - 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 + 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 hunk ./docs/building/building.sgml 3153 - file will match. The key pattern rules (in + file will match. The key pattern rules (in hunk ./docs/building/building.sgml 3178 + hunk ./docs/building/building.sgml 3180 - + + When the canned rule isn't right hunk ./docs/building/building.sgml 3183 - -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. + + hunk ./docs/building/building.sgml 3195 - -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. - + + Porting GHC hunk ./docs/building/building.sgml 3198 - + This section describes how to port GHC to a currenly + unsupported platform. There are two distinct + possibilities: hunk ./docs/building/building.sgml 3202 - + + + The hardware architecture for your system is already + supported by GHC, but you're running an OS that isn't + supported (or perhaps has been supported in the past, but + currently isn't). This is the easiest type of porting job, + but it still requires some careful bootstrapping. Proceed to + . + + + + Your system's hardware architecture isn't supported by + GHC. This will be a more difficult port (though by comparison + perhaps not as difficult as porting gcc). Proceed to . + + + + + Booting/porting from C (<filename>.hc</filename>) files hunk ./docs/building/building.sgml 3223 - -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> hunk ./docs/building/building.sgml 3227 -<indexterm><primary>building GHC from .hc files</primary></indexterm> -<indexterm><primary>booting GHC from .hc files</primary></indexterm> -<indexterm><primary>porting GHC</primary></indexterm> + Bootstrapping GHC on a system without GHC already + installed is achieved by taking the intermediate C files (known + as HC files) from a GHC compilation on a supported system to the + target machine, and compiling them using gcc to get a working + GHC. hunk ./docs/building/building.sgml 3233 - NOTE: GHC version 5.xx is significantly harder to - bootstrap from C than previous versions. We recommend starting - from version 4.08.2 if you need to bootstrap in this - way. + NOTE: GHC version 5.xx is significantly harder + to bootstrap from C than previous versions. We recommend + starting from version 4.08.2 if you need to bootstrap in this + way. hunk ./docs/building/building.sgml 3238 - -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''. - + HC files are architecture-dependent (but not + OS-dependent), so you have to get a set that were generated on + similar hardware. There may be some supplied on the GHC + download page, otherwise you'll have to compile some up + yourself, or start from unregisterised HC + files - see . hunk ./docs/building/building.sgml 3245 - -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. - + The following steps should result in a working GHC build + with full libraries: hunk ./docs/building/building.sgml 3248 - -Assuming you've got them, unpack them on top of a fresh source tree. This -will place matching .hc files next to the corresponding -Haskell source in the compiler subdirectory ghc and in -the language package of hslibs (i.e., in hslibs/lang). -Then follow the `normal' instructions in for setting up a build tree. - + + + Unpack the HC files on top of a fresh source tree + (make sure the source tree version matches the version of + the HC files exactly!). This will + place matching .hc files next to the + corresponding Haskell source (.hs or + .lhs) in the compiler subdirectory + ghc/compiler and in the libraries + (ghc/lib, and subdirectories of + hslibs). + + + + The actual build process is fully automated by the + hc-build script located in the + distrib directory. If you eventually + want to install GHC into the directory + dir, the following + command will execute the whole build process (it won't + install yet): hunk ./docs/building/building.sgml 3270 - -The actual build process is fully automated by the -hc-build script located in the -distrib directory. If you eventually want to install GHC -into the directory INSTALL_DIRECTORY, the following -command will execute the whole build process (it won't install yet): - hunk ./docs/building/building.sgml 3271 -foo% distrib/hc-build --prefix=INSTALL_DIRECTORY +foo% distrib/hc-build --prefix=dir hunk ./docs/building/building.sgml 3274 - -By default, the installation directory is /usr/local. If -that is what you want, you may omit the argument to -hc-build. Generally, any option given to -hc-build is passed through to the configuration script -configure. If hc-build -successfully completes the build process, you can install the resulting -system, as normal, with - + + By default, the installation directory is + /usr/local. If that is what you want, + you may omit the argument to hc-build. + Generally, any option given to hc-build + is passed through to the configuration script + configure. If + hc-build successfully completes the + build process, you can install the resulting system, as + normal, with + hunk ./docs/building/building.sgml 3288 + + + hunk ./docs/building/building.sgml 3292 - -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.) - + + Porting GHC to a new architecture + + The first step in porting to a new architecture is to get + an unregisterised build working. An + unregisterised build is one that compiles via vanilla C only. + By contrast, a registerised build uses the following + architecture-specific hacks for speed: + + + + Global register variables: certain abstract machine + registers are mapped to real machine + registers, depending on how many machine registers are + available (see + ghc/includes/MachRegs.h). + + + + Assembly-mangling: when compiling via C, we feed the + assembly generated by gcc though a Perl script known as the + mangler (see + ghc/driver/mangler/ghc-asm.lprl). The + mangler rearranges the assembly to support tail-calls and + various other optimisations. + + + + In an unregisterised build, neither of these hacks are + used — the idea is that the C code generated by the + compiler should compile using gcc only. The lack of these + optimisations costs about a factor of two in performance, but + since unregisterised compilation is usually just a step on the + way to a full registerised port, we don't mind too much. hunk ./docs/building/building.sgml 3327 - + + Building an unregisterised port + + The first step is to get some unregisterised HC files. + Either (a) download them from the GHC site (if there are + some available for the right version of GHC), or + (b) build them yourself on any machine with a working + GHC. + + There is a script available which should automate the + process of doing the 2-stage bootstrap necessary to get the + unregisterised HC files - it's available in fptools/distrib/cross-port + in CVS. + + Now take these unregisterised HC files to the target + platform and bootstrap a compiler from them as per the + instructions in . In + build.mk, you need to tell the build + system that the compiler you're building is + (a) unregisterised itself, and (b) builds + unregisterised binaries. This varies depending on the GHC + version you're bootstraping: hunk ./docs/building/building.sgml 3351 - -Known pitfalls in building Glasgow Haskell +<programlisting> +# build.mk for GHC 4.08.x +GhcWithRegisterised=NO +</programlisting> + +<programlisting> +# build.mk for GHC 5.xx +GhcUnregisterised=YES +</programlisting> + + <para>Version 5.xx only: use the option + <option>--enable-hc-boot-unregisterised</option> instead of + <option>--enable-hc-boot</option> when running + <filename>./configure</filename>.</para> + + <para>The build may not go through cleanly. We've tried to + stick to writing portable code in most parts of the compiler, + so it should compile on any POSIXish system with gcc, but in + our experience most systems differ from the standards in one + way or another. Deal with any problems as they arise - if you + get stuck, ask the experts on + <email>glasgow-haskell-users@haskell.org</email>.</para> + + <para>Once you have the unregisterised compiler up and + running, you can use it to start a registerised port. The + following sections describe the various parts of the system + that will need architecture-specific tweaks in order to get a + registerised build going.</para> + + <para>Lots of useful information about the innards of GHC is + available in the <ulink + url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC + Commentary</ulink>, which might be helpful if you run into + some code which needs tweaking for your system.</para> + </sect3> + + <sect3> + <title>Porting the RTS + + The following files need architecture-specific code for a + registerised build: + + + + ghc/includes/MachRegs.h + MachRegs.h + + + Defines the STG-register to machine-register + mapping. You need to know your platform's C calling + convention, and which registers are generally available + for mapping to global register variables. There are + plenty of useful comments in this file. + + + + ghc/includes/TailCalls.h + TailCalls.h + + + Macros that cooperate with the mangler (see ) to make proper tail-calls + work. + + + + ghc/rts/Adjustor.c + Adjustor.c + + + Support for + foreign import "wrapper" + (aka + foreign export dynamic). + Not essential for getting GHC bootstrapped, so this file + can be deferred until later if necessary. + + + + ghc/rts/StgCRun.c + StgCRun.c + + + The little assembly layer between the C world and + the Haskell world. See the comments and code for the + other architectures in this file for pointers. + + + + ghc/rts/MBlock.h + ghc/rts/MBlock.c + MBlock.h + + MBlock.c + + + These files are really OS-specific rather than + architecture-specific. In MBlock.h + is specified the absolute location at which the RTS + should try to allocate memory on your platform (try to + find an area which doesn't conflict with code or dynamic + libraries). In Mblock.c you might + need to tweak the call to mmap() for + your OS. + + + + + + + The mangler + + The mangler is an evil Perl-script that rearranges the + assembly code output from gcc to do two main things: + + + + Remove function prologues and epilogues, and all + movement of the C stack pointer. This is to support + tail-calls: every code block in Haskell code ends in an + explicit jump, so we don't want the C-stack overflowing + while we're jumping around between code blocks. + + + Move the info table for a + closure next to the entry code for that closure. In + unregisterised code, info tables contain a pointer to the + entry code, but in registerised compilation we arrange + that the info table is shoved right up against the entry + code, and addressed backwards from the entry code pointer + (this saves a word in the info table and an extra + indirection when jumping to the closure entry + code). + + + + The mangler is abstracted to a certain extent over some + architecture-specific things such as the particular assembler + directives used to herald symbols. Take a look at the + definitions for other architectures and use these as a + starting point. + + + + The native code generator + + The native code generator isn't essential to getting a + registerised build going, but it's a desirable thing to have + because it can cut compilation times in half. The native code + generator is described in some detail in the GHC + commentary. + + + + GHCi + + To support GHCi, you need to port the dynamic linker + (fptools/ghc/rts/Linker.c). The linker + currently supports the ELF and PEi386 object file formats - if + your platform uses one of these then you probably don't have + to do anything except fiddle with the + #ifdefs at the top of + Linker.c to tell it about your OS. + + If your system uses a different object file format, then + you have to write a linker — good luck! + + + + + + +Known pitfalls in building Glasgow Haskell hunk ./docs/building/building.sgml 3528 -<indexterm><primary>building pitfalls</primary></indexterm> +building pitfalls hunk ./docs/building/building.sgml 3531 -WARNINGS about pitfalls and known ``problems'': +WARNINGS about pitfalls and known “problems”: hunk ./docs/building/building.sgml 3546 -The quickest way around it is setenv TMPDIR /usr/tmpTMPDIR or -even setenv TMPDIR . (or the equivalent incantation with your shell +The quickest way around it is setenv TMPDIR /usr/tmpTMPDIR or +even setenv TMPDIR . (or the equivalent incantation with your shell hunk ./docs/building/building.sgml 3557 -Then GHC and the other fptools programs will use the appropriate directory +Then GHC and the other fptools programs will use the appropriate directory hunk ./docs/building/building.sgml 3575 -When compiling via C, you'll sometimes get ``warning: assignment from -incompatible pointer type'' out of GCC. Harmless. +When compiling via C, you'll sometimes get “warning: assignment from +incompatible pointer type” out of GCC. Harmless. hunk ./docs/building/building.sgml 3583 -Similarly, archiving warning messages like the following are not +Similarly, archiving warning messages like the following are not hunk ./docs/building/building.sgml 3598 - In compiling the compiler proper (in compiler/), you may -get an ``Out of heap space'' error message. These can vary with the + In compiling the compiler proper (in compiler/), you may +get an “Out of heap space” error message. These can vary with the hunk ./docs/building/building.sgml 3603 - + hunk ./docs/building/building.sgml 3608 -maximum heap size must have been reached. This +maximum heap size must have been reached. This hunk ./docs/building/building.sgml 3611 - flag (add this flag to + flag (add this flag to hunk ./docs/building/building.sgml 3613 -make variable in the appropriate +make variable in the appropriate hunk ./docs/building/building.sgml 3621 - For GHC < 4.00, add a suitable flag to the Makefile, as + For GHC < 4.00, add a suitable flag to the Makefile, as hunk ./docs/building/building.sgml 3627 - + hunk ./docs/building/building.sgml 3630 -and try again: gmake. (see for information about +and try again: gmake. (see for information about hunk ./docs/building/building.sgml 3648 -mis-installed. fixincludes wasn't run when it should've been. +mis-installed. fixincludes wasn't run when it should've been. hunk ./docs/building/building.sgml 3650 -As fixincludes is now automagically run as part of GCC installation, +As fixincludes is now automagically run as part of GCC installation, hunk ./docs/building/building.sgml 3659 -You may need to re-ranlibranlib your libraries (on Sun4s). +You may need to re-ranlibranlib your libraries (on Sun4s). hunk ./docs/building/building.sgml 3679 -GHC's sources go through cpp before being compiled, and cpp varies +GHC's sources go through cpp before being compiled, and cpp varies hunk ./docs/building/building.sgml 3689 -Some cpps treat the comma inside the string as separating two macro +Some cpps treat the comma inside the string as separating two macro hunk ./docs/building/building.sgml 3698 -Alas, cpp doesn't tell you the offending file! +Alas, cpp doesn't tell you the offending file! hunk ./docs/building/building.sgml 3700 -Workaround: don't put weird things in string args to cpp macros. +Workaround: don't put weird things in string args to cpp macros. hunk ./docs/building/building.sgml 3708 - + hunk ./docs/building/building.sgml 3711 -Notes for building under Windows +Notes for building under Windows hunk ./docs/building/building.sgml 3723 -Before you start +Before you start hunk ./docs/building/building.sgml 3729 -MAKE_MODE is set to UNIX. If you +MAKE_MODE is set to UNIX. If you hunk ./docs/building/building.sgml 3731 -make, such as: +make, such as: hunk ./docs/building/building.sgml 3753 - - hunk ./docs/building/building.sgml 3756 - + }