diff options
| author | rrt <unknown> | 2000-10-12 15:39:41 +0000 |
|---|---|---|
| committer | rrt <unknown> | 2000-10-12 15:39:41 +0000 |
| commit | 5b5289692e3f720cc31f3aad22d496d561018fa9 (patch) | |
| tree | 583b03fca816f055e9c119312d0b88af8cf71693 /docs/building.sgml | |
| parent | 5e2b22a5efbc9444a56346f3f93d863703dd1263 (diff) | |
| download | haskell-5b5289692e3f720cc31f3aad22d496d561018fa9.tar.gz | |
[project @ 2000-10-12 15:39:41 by rrt]
Moved into subdirectories to allow docs to be built by build system.
Diffstat (limited to 'docs/building.sgml')
| -rw-r--r-- | docs/building.sgml | 2988 |
1 files changed, 0 insertions, 2988 deletions
diff --git a/docs/building.sgml b/docs/building.sgml deleted file mode 100644 index 3836d234b7..0000000000 --- a/docs/building.sgml +++ /dev/null @@ -1,2988 +0,0 @@ -<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> - -<Article id="building-guide"> - -<ArtHeader> - -<Title>Building the Glasgow Functional Programming Tools Suite</Title> -<Author><OtherName>The GHC Team</OtherName></Author> -<Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address> -<PubDate>January 2000</PubDate> - -<Abstract> - -<Para> -This guide is intended for people who want to build or modify -programs from the Glasgow <Literal>fptools</Literal> suite (as distinct from those -who merely want to <Emphasis>run</Emphasis> them). Installation instructions are now provided in the user guide. -</Para> - -<Para> -The bulk of this guide applies to building on Unix systems; see <XRef LinkEnd="winbuild"> for Windows notes. -</Para> - -</Abstract> - -</ArtHeader> - - -<Sect1 id="sec-getting"> -<Title>Getting the Glasgow <Literal>fptools</Literal> suite -</Title> - -<Para> -Building the Glasgow tools <Emphasis>can</Emphasis> 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! -</Para> - -<Para> -Happily, such complications don't apply to most people. A few common -``strategies'' serve most purposes. Pick one and proceed -as suggested: -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term><IndexTerm><Primary>Binary distribution</Primary></IndexTerm>Binary distribution.</Term> -<ListItem> -<Para> -If your only purpose is to install some of the <Literal>fptools</Literal> 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. -</Para> - -<Para> -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. -</Para> - -<Para> -The second reason a binary distribution may not be what you want is -if you want to read or modify the souce code. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><IndexTerm><Primary>Source distribution</Primary></IndexTerm>Source distribution.</Term> -<ListItem> -<Para> -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. -</Para> - -<Para> -A source distribution contains complete sources for one or more -projects in the <Literal>fptools</Literal> suite. Not only that, but the more awkward -machine-independent steps are done for you. For example, if you don't -have <Command>flex</Command><IndexTerm><Primary>flex</Primary></IndexTerm> you'll find it convenient that the source -distribution contains the result of running <Command>flex</Command> on the lexical -analyser specification. If you don't want to alter the lexical -analyser then this saves you having to find and install <Command>flex</Command>. You -will still need a working version of GHC on your machine in order to -compile (most of) the sources, however. -</Para> - -<Para> -We make source distributions more frequently than binary -distributions; a release that comes with pre-compiled binaries -is considered a major release, i.e., a release that we have some -confidence will work well by having tested it (more) thoroughly. -</Para> - -<Para> -Source-only distributions are either bugfix releases or snapshots of -current state of development. The release has undergone some testing. -Source releases of GHC 4.xx can be compiled up using GHC 2.10 or -later. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term>Build GHC from intermediate C <Filename>.hc</Filename> files<IndexTerm><Primary>hc files</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -You -need a working GHC to use a source distribution. What if you don't -have a working GHC? Then you have no choice but to ``bootstrap'' up -from the intermediate C (<Filename>.hc</Filename>) files that we provide. Building GHC -on an unsupported platform falls into this category. Please see -<Xref LinkEnd="sec-booting-from-C">. -</Para> - -<Para> -Once you have built GHC, you can build the other Glasgow tools with -it. -</Para> - -<Para> -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). -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term>The CVS repository.</Term> -<ListItem> -<Para> -We make source distributions slightly more often than binary -distributions; but still infrequently. If you want more up-to-the -minute (but less tested) source code then you need to get access to -our CVS repository. -</Para> - -<Para> -All the <Literal>fptools</Literal> source code is held in a CVS repository. CVS is a -pretty good source-code control system, and best of all it works over -the network. -</Para> - -<Para> -The repository holds source code only. It holds no mechanically -generated files at all. So if you check out a source tree from CVS -you will need to install every utility so that you can build all the -derived files from scratch. -</Para> - -<Para> -More information about our CVS repository is available in the <ULink -URL="http://www.haskell.org/ghc/cvs-cheat-sheet.html" >FPTools CVS -Cheat Sheet</ULink >. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -If you are going to do any building from sources (either from a source -distribution or the CVS repository) then you need to read all of this -manual in detail. -</Para> - -</Sect1> - -<Sect1 id="sec-build-checks"> -<Title>Things to check before you start typing</Title> - -<Para> -Here's a list of things to check before you get started. - -<OrderedList> -<ListItem> - -<Para> -<IndexTerm><Primary>Disk space needed</Primary></IndexTerm> -Disk space needed: About 40MB (one tenth of one hamburger's worth) of disk -space for the most basic binary distribution of GHC; more for some -platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent Haskell -libraries) might take you to up to one fifth of a hamburger. You'll need -over 100MB (say, one fifth a hamburger's worth) if you need to build the -basic stuff from scratch. All of the above are -<Emphasis>estimates</Emphasis> of disk-space needs. (Note: our benchmark hamburger is a standard Double Whopper with Cheese, with an RRP of UKP2.99.) -</Para> -</ListItem> -<ListItem> - -<Para> -Use an appropriate machine, compilers, and things. -SPARC boxes, and PCs running Linux, FreeBSD, NetBSD, or Solaris are -all fully supported. Win32 and HP boxes are in pretty good shape. -DEC Alphas running OSF/1, Linux or some BSD variant, MIPS and AIX -boxes will need some minimal porting effort before they work (as of -4.06). <Xref LinkEnd="sec-port-info"> gives the full run-down on -ports or lack thereof. -</Para> -</ListItem> -<ListItem> - -<Para> - Be sure that the ``pre-supposed'' utilities are installed. -<Xref LinkEnd="sec-pre-supposed"> elaborates. - -</Para> -</ListItem> -<ListItem> - -<Para> - If you have any problem when building or installing the Glasgow -tools, please check the ``known pitfalls'' (<Xref -LinkEnd="sec-build-pitfalls">). Also check the FAQ for the version -you're building, which should be available from the relevant download -page on the <ULink URL="http://www.haskell.org/ghc/" >GHC web -site</ULink>. - -<IndexTerm><Primary>known bugs</Primary></IndexTerm> -<IndexTerm><Primary>bugs, known</Primary></IndexTerm> - -If you feel there is still some shortcoming in our procedure or -instructions, please report it. - -For GHC, please see the bug-reporting section of the GHC Users' Guide -(separate document), to maximise the usefulness of your report. -<IndexTerm><Primary>bugs, reporting</Primary></IndexTerm> - -If in doubt, please send a message to -<Email>glasgow-haskell-bugs@haskell.org</Email>. -<IndexTerm><Primary>bugs, mailing list</Primary></IndexTerm> -</Para> -</ListItem> - -</OrderedList> - -</Para> - -</Sect1> - -<Sect1 id="sec-port-info"> -<Title>What machines the Glasgow tools run on -</Title> - -<Para> -<IndexTerm><Primary>ports, GHC</Primary></IndexTerm> -<IndexTerm><Primary>GHC ports</Primary></IndexTerm> -<IndexTerm><Primary>supported platforms</Primary></IndexTerm> -<IndexTerm><Primary>platforms, supported</Primary></IndexTerm> -The main question is whether or not the Haskell compiler (GHC) runs on -your platform. -</Para> - -<Para> -A ``platform'' is a architecture/manufacturer/operating-system -combination, such as <Literal>sparc-sun-solaris2</Literal>. Other common ones are -<Literal>alpha-dec-osf2</Literal>, <Literal>hppa1.1-hp-hpux9</Literal>, <Literal>i386-unknown-linux</Literal>, -<Literal>i386-unknown-solaris2</Literal>, <Literal>i386-unknown-freebsd</Literal>, -<Literal>i386-unknown-cygwin32</Literal>, <Literal>m68k-sun-sunos4</Literal>, <Literal>mips-sgi-irix5</Literal>, -<Literal>sparc-sun-sunos4</Literal>, <Literal>sparc-sun-solaris2</Literal>, <Literal>powerpc-ibm-aix</Literal>. -</Para> - -<Para> -Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not -work on all machines for which basic Haskell compiling is supported. -</Para> - -<Para> -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. -</Para> - -<Sect2> -<Title>What platforms the Haskell compiler (GHC) runs on</Title> - -<Para> -<IndexTerm><Primary>fully-supported platforms</Primary></IndexTerm> -<IndexTerm><Primary>native-code generator</Primary></IndexTerm> -<IndexTerm><Primary>registerised ports</Primary></IndexTerm> -<IndexTerm><Primary>unregisterised ports</Primary></IndexTerm> -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). -</Para> - -<Para> -The native code generator is currently non-functional (as of GHC -version 4.06), but we're actively working on getting it going again. -</Para> - -<Para> -We use Sparcs running Solaris 2.7 and x86 boxes running FreeBSD and -Linux, so those are the best supported platforms, unsurprisingly. -</Para> - -<Para> -Here's everything that's known about GHC ports. We identify platforms -by their ``canonical'' CPU/Manufacturer/OS triple. -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</Term> -<IndexTerm><Primary>alpha-dec-osf</Primary></IndexTerm> -<IndexTerm><Primary>alpha-dec-linux</Primary></IndexTerm> -<IndexTerm><Primary>alpha-dec-freebsd</Primary></IndexTerm> -<IndexTerm><Primary>alpha-dec-openbsd</Primary></IndexTerm> -<IndexTerm><Primary>alpha-dec-netbsd</Primary></IndexTerm> -<ListItem> - -<Para> -Currently non-working. The last working version (osf[1-3]) is GHC -3.02. A small amount of porting effort will be required to get Alpha -support into GHC 4.xx, but we don't have easy access to machines right -now, and there hasn't been a massive demand for support, so Alphas -remain unsupported for the time being. Please get in touch if you -either need Alpha support and/or can provide access to boxes. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>sparc-sun-sunos4:</Term> -<IndexTerm><Primary>sparc-sun-sunos4</Primary></IndexTerm> -<ListItem> - -<Para> -Probably works with minor tweaks, hasn't been tested for a while. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>sparc-sun-solaris2:</Term> -<IndexTerm><Primary>sparc-sun-solaris2</Primary></IndexTerm> -<ListItem> - -<Para> -Fully supported, including native-code generator. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</Term> -<IndexTerm><Primary>hppa1.1-hp-hpux</Primary></IndexTerm> -<ListItem> - -<Para> -Works registerised. No native-code generator. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>i386-unknown-linux (PCs running Linux—ELF binary format):</Term> -<IndexTerm><Primary>i386-*-linux</Primary></IndexTerm> -<ListItem> - -<Para> -GHC works registerised. You <Emphasis>must</Emphasis> have GCC 2.7.x -or later. NOTE about <literal>glibc</literal> versions: GHC binaries -built on a system running <literal>glibc 2.0</literal> won't work on a -system running <literal>glibc 2.1</literal>, and vice version. In -general, don't expect compatibility between <literal>glibc</literal> -versions, even if the shared library version hasn't changed. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>i386-unknown-{freebsd,netbsd,openbsd) (PCs running FreeBSD 2.2 -or higher, NetBSD, and possibly OpenBSD):</Term> -<IndexTerm><Primary>i386-unknown-freebsd</Primary></IndexTerm> -<IndexTerm><Primary>i386-unknown-netbsd</Primary></IndexTerm> -<IndexTerm><Primary>i386-unknown-openbsd</Primary></IndexTerm> -<ListItem> - -<Para> -GHC works registerised. These systems provide ready-built packages of -GHC, so if you just need binaries you're better off just installing -the package. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>i386-unknown-cygwin32:</Term> -<IndexTerm><Primary>i386-unknown-cygwin32</Primary></IndexTerm> -<ListItem> - -<Para> -Fully supported under Win9x/NT, including a native code -generator. Requires the <Literal>cygwin32</Literal> compatibility -library and a healthy collection of GNU tools (i.e., gcc, GNU ld, bash -etc.). -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>mips-sgi-irix5:</Term> -<IndexTerm><Primary>mips-sgi-irix[5-6]</Primary></IndexTerm> -<ListItem> - -<Para> -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. -</Para> -</ListItem></VarListEntry> - -<VarListEntry> -<Term>powerpc-ibm-aix:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>powerpc-ibm-aix</Primary></IndexTerm> -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. -</Para> -</ListItem></VarListEntry> - -</VariableList> -</Para> - -<para> -Various other systems have had GHC ported to them in the distant past, -including various Motorola 68k boxes. The 68k support still remains, -but porting to one of these systems will certainly be a non-trivial -task. -</para> - -</Sect2> - -<Sect2> -<Title>What machines the other tools run on</Title> - -<Para> -Unless you hear otherwise, the other tools work if GHC works. -</Para> - -</Sect2> - -</Sect1> - - -<Sect1 id="sec-pre-supposed"> -<Title>Installing pre-supposed utilities - -<IndexTerm><Primary>pre-supposed utilities</Primary></IndexTerm> -<IndexTerm><Primary>utilities, pre-supposed</Primary></IndexTerm></Title> - -<Para> -Here are the gory details about some utility programs you may need; -<Command>perl</Command>, <Command>gcc</Command> and -<command>happy</command> are the only important -ones. (PVM<IndexTerm><Primary>PVM</Primary></IndexTerm> is important -if you're going for Parallel Haskell.) The -<Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm> -script will tell you if you are missing something. -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term>Perl:</Term> -<IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm> -<IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm> -<ListItem> -<Para> -<Emphasis>You have to have Perl to proceed!</Emphasis> Perl is a -language quite good for doing shell-scripty tasks that involve lots of -text processing. It is pretty easy to install. -</Para> - -<Para> -Perl 5 is required. For Win32 platforms, we strongly suggest you -pick up a port of Perl 5 for <Literal>cygwin32</Literal>, as the -common Hip/ActiveWare port of Perl is Not Cool Enough for our -purposes. -</Para> - -<Para> -Perl should be put somewhere so that it can be invoked by the -<Literal>#!</Literal> script-invoking mechanism. (I believe -<Filename>/usr/bin/perl</Filename> is preferred; we use -<Filename>/usr/local/bin/perl</Filename> at Glasgow.) The full -pathname should may need to be less than 32 characters long on some -systems. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term>GNU C (<Command>gcc</Command>):</Term> -<IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm> -<IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm> -<ListItem> - -<Para> -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 <command>egcs</command>) have varying degrees of stability -depending on the platform. -</Para> - -<Para> -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>-monly-N-regs</Option> option; see the User's Guide) -</Para> -</ListItem></VarListEntry> - -<varlistentry> -<term>Happy:</term> -<indexterm><primary>Happy</primary></indexterm> -<listitem> -<para>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 (<literal>fptools/happy</literal>). 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 <ulink -url="http://www.haskell.org/happy/">Happy's Web Page</ulink>. -</para> -</listitem> -</varlistentry> - -<VarListEntry> -<Term>Autoconf:</Term> -<IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm> -<IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm> -<ListItem> -<Para> -GNU Autoconf is needed if you intend to build from the CVS sources, it -is <Emphasis>not</Emphasis> needed if you just intend to build a -standard source distribution. -</Para> - -<Para> -Autoconf builds the <Command>configure</Command> script from -<Filename>configure.in</Filename> and <Filename>aclocal.m4</Filename>. -If you modify either of these files, you'll need Autoconf to rebuild -<Filename>configure</Filename>. -</Para> - -</ListItem></VarListEntry> -<VarListEntry> -<Term><Command>sed</Command></Term> -<IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm> -<IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm> -<ListItem> -<Para> -You need a working <Command>sed</Command> 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.) -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -One <Literal>fptools</Literal> project is worth a quick note at this -point, because it is useful for all the others: -<Literal>glafp-utils</Literal> contains several utilities which aren't -particularly Glasgow-ish, but Occasionally Indispensable. Like -<Command>lndir</Command> for creating symbolic link trees. -</Para> - -<Sect2 id="pre-supposed-gph-tools"> -<Title>Tools for building parallel GHC (GPH) -</Title> - -<Para> -<VariableList> - -<VarListEntry> -<Term>PVM version 3:</Term> -<IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm> -<IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm> -<ListItem> - -<Para> -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). -</Para> - -<Para> -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 -<Literal>research.att.com</Literal>, in <Filename>netlib</Filename>. -</Para> - -<Para> -A PVM installation is slightly quirky, but easy to do. Just follow -the <Filename>Readme</Filename> instructions. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Command>bash</Command>:</Term> -<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm> -<ListItem> -<Para> -Sadly, the <Command>gr2ps</Command> script, used to convert ``parallelism profiles'' -to PostScript, is written in Bash (GNU's Bourne Again shell). -This bug will be fixed (someday). -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -</Sect2> - -<Sect2 id="pre-supposed-doc-tools"> -<Title>Tools for building the Documentation -</Title> - -<Para> -The following additional tools are required if you want to format the -documentation that comes with the <Literal>fptools</Literal> projects: -</Para> - -<Para> -<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> -<VarListEntry> -<Term>TeX:</Term> -<IndexTerm><Primary>pre-supposed: TeX</Primary></IndexTerm> -<IndexTerm><Primary>TeX, pre-supposed</Primary></IndexTerm> -<ListItem> -<Para> -A decent TeX distribution is required if you want to produce printable -documentation. We recomment teTeX, which includes just about -everything you need. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -</Sect2> - -<Sect2 id="pre-supposed-other-tools"> -<Title>Other useful tools -</Title> - -<VariableList> -<VarListEntry> -<Term>Flex:</Term> -<IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm> -<IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm> -<ListItem> - -<Para> -This is a quite-a-bit-better-than-Lex lexer. Used to build a couple -of utilities in <Literal>glafp-utils</Literal>. Depending on your -operating system, the supplied <Command>lex</Command> may or may not -work; you should get the GNU version. -</Para> -</ListItem></VarListEntry> -</VariableList> - -</Sect2> - -</Sect1> - -<Sect1 id="sec-building-from-source"> -<Title>Building from source - -<IndexTerm><Primary>Building from source</Primary></IndexTerm> -<IndexTerm><Primary>Source, building from</Primary></IndexTerm></Title> - -<Para> -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. -</Para> - -<Para> -Gingerly, you type <Command>make</Command>. Wrong already! -</Para> - -<Para> -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. -</Para> - -<Sect2 id="sec-source-tree"> -<Title>Your source tree -</Title> - -<Para> -The source code is held in your <Emphasis>source tree</Emphasis>. -The root directory of your source tree <Emphasis>must</Emphasis> -contain the following directories and files: -</Para> - -<Para> - -<ItemizedList> -<ListItem> - -<Para> -<Filename>Makefile</Filename>: the root Makefile. -</Para> -</ListItem> -<ListItem> - -<Para> -<Filename>mk/</Filename>: the directory that contains the -main Makefile code, shared by all the -<Literal>fptools</Literal> software. -</Para> -</ListItem> -<ListItem> - -<Para> - <Filename>configure.in</Filename>, <Filename>config.sub</Filename>, <Filename>config.guess</Filename>: -these files support the configuration process. -</Para> -</ListItem> -<ListItem> - -<Para> - <Filename>install-sh</Filename>. -</Para> -</ListItem> - -</ItemizedList> - -</Para> - -<Para> -All the other directories are individual <Emphasis>projects</Emphasis> of the -<Literal>fptools</Literal> system—for example, the Glasgow Haskell Compiler -(<Literal>ghc</Literal>), the Happy parser generator (<Literal>happy</Literal>), the <Literal>nofib</Literal> benchmark -suite, and so on. You can have zero or more of these. Needless to -say, some of them are needed to build others. -</Para> - -<Para> -The important thing to remember is that even if you want only one -project (<Literal>happy</Literal>, say), you must have a source tree whose root -directory contains <Filename>Makefile</Filename>, <Filename>mk/</Filename>, <Filename>configure.in</Filename>, and the -project(s) you want (<Filename>happy/</Filename> in this case). You cannot get by with -just the <Filename>happy/</Filename> directory. -</Para> - -</Sect2> - -<Sect2> -<Title>Build trees -<IndexTerm><Primary>build trees</Primary></IndexTerm> -<IndexTerm><Primary>link trees, for building</Primary></IndexTerm></Title> - -<Para> -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. -</Para> - -<Para> -So for every source tree we have zero or more <Emphasis>build trees</Emphasis>. 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: -<Command>lndir</Command><IndexTerm><Primary>lndir</Primary></IndexTerm>, <Command>mkshadowdir</Command><IndexTerm><Primary>mkshadowdir</Primary></IndexTerm> are two (If you -don't have either, the source distribution includes sources for the -X11 <Command>lndir</Command>—check out <Filename>fptools/glafp-utils/lndir</Filename>). See <Xref LinkEnd="sec-storysofar"> for a typical invocation. -</Para> - -<Para> -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—<XRef LinkEnd="sec-build-config">) -<Emphasis>absolutely everything in the build tree is either a symbolic -link to the source tree, or else is mechanically generated</Emphasis>. -It should be perfectly OK for your build tree to vanish overnight; an -hour or two compiling and you're on the road again. -</Para> - -<Para> -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! -</Para> - -<Para> -Remember, that the source files in the build tree are <Emphasis>symbolic -links</Emphasis> to the files in the source tree. (The build tree soon -accumulates lots of built files like <Filename>Foo.o</Filename>, as well.) You -can <Emphasis>delete</Emphasis> 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 <Emphasis>edit</Emphasis> 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.) -</Para> - -<Para> -Like the source tree, the top level of your build tree must be (a -linked copy of) the root directory of the <Literal>fptools</Literal> suite. Inside -Makefiles, the root of your build tree is called -<Constant>$(FPTOOLS_TOP)</Constant><IndexTerm><Primary>FPTOOLS_TOP</Primary></IndexTerm>. In the rest of this document path -names are relative to <Constant>$(FPTOOLS_TOP)</Constant> unless otherwise stated. For -example, the file <Filename>ghc/mk/target.mk</Filename> is actually -<Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc/mk/target.mk</Filename>. -</Para> - -</Sect2> - -<Sect2 id="sec-build-config"> -<Title>Getting the build you want -</Title> - -<Para> -When you build <Literal>fptools</Literal> you will be compiling code on a particular -<Emphasis>host platform</Emphasis>, to run on a particular <Emphasis>target platform</Emphasis> -(usually the same as the host platform)<IndexTerm><Primary>platform</Primary></IndexTerm>. 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. -</Para> - -<Para> -There are also knobs you can turn to control how the <Literal>fptools</Literal> -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. -</Para> - -<Para> -All of this stuff is called the <Emphasis>configuration</Emphasis> of your build. -You set the configuration using a three-step process. -<VariableList> - -<VarListEntry> -<Term>Step 1: get ready for configuration.</Term> -<ListItem> -<Para> -Change directory to -<Constant>$(FPTOOLS_TOP)</Constant> and issue the command <Command>autoconf</Command><IndexTerm><Primary>autoconf</Primary></IndexTerm> (with -no arguments). This GNU program converts <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure.in</Filename> -to a shell script called <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure</Filename>. -</Para> - -<para> -Some projects, including GHC, have their own configure script. If -there's an -<Constant>$(FPTOOLS_TOP)/<project>/configure.in</Constant>, -then you need to run <command>autoconf</command> in that directory too. -</para> - -<Para> -Both these steps are completely platform-independent; they just mean -that the human-written file (<Filename>configure.in</Filename>) can be short, although -the resulting shell script, <Command>configure</Command>, and <Filename>mk/config.h.in</Filename>, are -long. -</Para> - -<Para> -In case you don't have <Command>autoconf</Command> we distribute the results, -<Command>configure</Command>, and <Filename>mk/config.h.in</Filename>, with the source distribution. They -aren't kept in the repository, though. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term>Step 2: system configuration.</Term> -<ListItem> -<Para> -Runs the newly-created <Command>configure</Command> script, thus: - -<ProgramListing> -./configure -</ProgramListing> - -<Command>configure</Command>'s mission is to scurry round your -computer working out what architecture it has, what operating system, -whether it has the <Function>vfork</Function> system call, where -<Command>yacc</Command> is kept, whether <Command>gcc</Command> is -available, where various obscure <Literal>#include</Literal> 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: -</Para> - -<Para> - -<ItemizedList> -<ListItem> - -<Para> - It translates <Filename>mk/config.mk.in</Filename><IndexTerm><Primary>config.mk.in</Primary></IndexTerm> to -<Filename>mk/config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm>, substituting for things between -``<Literal>@</Literal>'' brackets. So, ``<Literal>@HaveGcc@</Literal>'' will be replaced by -``<Literal>YES</Literal>'' or ``<Literal>NO</Literal>'' depending on what <Command>configure</Command> finds. -<Filename>mk/config.mk</Filename> is included by every Makefile (directly or indirectly), -so the configuration information is thereby communicated to all -Makefiles. - -</Para> -</ListItem> -<ListItem> - -<Para> - It translates <Filename>mk/config.h.in</Filename><IndexTerm><Primary>config.h.in</Primary></IndexTerm> to -<Filename>mk/config.h</Filename><IndexTerm><Primary>config.h</Primary></IndexTerm>. The latter is <Literal>#include</Literal>d by various C -programs, which can thereby make use of configuration information. - -</Para> -</ListItem> - -</ItemizedList> - -</Para> - -<Para> -<Command>configure</Command> caches the results of its run in <Filename>config.cache</Filename>. Quite -often you don't want that; you're running <Command>configure</Command> a second time -because something has changed. In that case, simply delete -<Filename>config.cache</Filename>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term>Step 3: build configuration.</Term> -<ListItem> -<Para> -Next, you say how this build of <Literal>fptools</Literal> is to differ from the -standard defaults by creating a new file <Filename>mk/build.mk</Filename><IndexTerm><Primary>build.mk</Primary></IndexTerm> -<Emphasis>in the build tree</Emphasis>. 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 <Filename>build.mk</Filename> files, and use a -symbolic link in each build tree to point to the appropriate one.) So -<Filename>mk/build.mk</Filename> 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. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -And that's it for configuration. Simple, eh? -</Para> - -<Para> -What do you put in your build-specific configuration file -<Filename>mk/build.mk</Filename>? <Emphasis>For almost all purposes all you will do is put -make variable definitions that override those in</Emphasis> <Filename>mk/config.mk.in</Filename>. -The whole point of <Filename>mk/config.mk.in</Filename>—and its derived counterpart -<Filename>mk/config.mk</Filename>—is to define the build configuration. It is heavily -commented, as you will see if you look at it. So generally, what you -do is look at <Filename>mk/config.mk.in</Filename>, and add definitions in <Filename>mk/build.mk</Filename> -that override any of the <Filename>config.mk</Filename> definitions that you want to -change. (The override occurs because the main boilerplate file, -<Filename>mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>, includes <Filename>build.mk</Filename> after -<Filename>config.mk</Filename>.) -</Para> - -<Para> -For example, <Filename>config.mk.in</Filename> contains the definition: -</Para> - -<Para> - -<ProgramListing> -ProjectsToBuild = glafp-utils ghc hslibs -</ProgramListing> - -</Para> - -<Para> -The accompanying comment explains that this is the list of enabled -projects; that is, if (after configuring) you type <Command>gmake all</Command> in -<Constant>FPTOOLS_TOP</Constant> three specified projects will be made. If you want to -add <Command>green-card</Command>, you can add this line to <Filename>build.mk</Filename>: -</Para> - -<Para> - -<ProgramListing> -ProjectsToBuild += green-card -</ProgramListing> - -</Para> - -<Para> -or, if you prefer, -</Para> - -<Para> - -<ProgramListing> -ProjectsToBuild = glafp-utils ghc green-card -</ProgramListing> - -</Para> - -<Para> -(GNU <Command>make</Command> allows existing definitions to have new text appended -using the ``<Literal>+=</Literal>'' operator, which is quite a convenient feature.) -</Para> - -<Para> -When reading <Filename>config.mk.in</Filename>, remember that anything between -``@...@'' signs is going to be substituted by <Command>configure</Command> -later. You <Emphasis>can</Emphasis> override the resulting definition if you want, -but you need to be a bit surer what you are doing. For example, -there's a line that says: -</Para> - -<Para> - -<ProgramListing> -YACC = @YaccCmd@ -</ProgramListing> - -</Para> - -<Para> -This defines the Make variables <Constant>YACC</Constant> to the pathname for a <Command>yacc</Command> that -<Command>configure</Command> finds somewhere. If you have your own pet <Command>yacc</Command> you want -to use instead, that's fine. Just add this line to <Filename>mk/build.mk</Filename>: -</Para> - -<Para> - -<ProgramListing> -YACC = myyacc -</ProgramListing> - -</Para> - -<Para> -You do not <Emphasis>have</Emphasis> to have a <Filename>mk/build.mk</Filename> file at all; if you -don't, you'll get all the default settings from <Filename>mk/config.mk.in</Filename>. -</Para> - -<Para> -You can also use <Filename>build.mk</Filename> to override anything that <Command>configure</Command> got -wrong. One place where this happens often is with the definition of -<Constant>FPTOOLS_TOP_ABS</Constant>: this variable is supposed to be the canonical path -to the top of your source tree, but if your system uses an automounter -then the correct directory is hard to find automatically. If you find -that <Command>configure</Command> has got it wrong, just put the correct definition in -<Filename>build.mk</Filename>. -</Para> - -</Sect2> - -<Sect2 id="sec-storysofar"> -<Title>The story so far</Title> - -<Para> -Let's summarise the steps you need to carry to get yourself -a fully-configured build tree from scratch. -</Para> - -<Para> - -<OrderedList> -<ListItem> - -<Para> - Get your source tree from somewhere (CVS repository or source -distribution). Say you call the root directory <Filename>myfptools</Filename> (it -does not have to be called <Filename>fptools</Filename>). Make sure that you have -the essential files (see <XRef LinkEnd="sec-source-tree">). - -</Para> -</ListItem> -<ListItem> - -<Para> - Use <Command>lndir</Command> or <Command>mkshadowdir</Command> to create a build tree. - -<ProgramListing> -cd myfptools -mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 -</ProgramListing> - -(N.B. <Command>mkshadowdir</Command>'s first argument is taken relative to its second.) You probably want to give the build tree a name that -suggests its main defining characteristic (in your mind at least), -in case you later add others. - -</Para> -</ListItem> -<ListItem> - -<Para> - Change directory to the build tree. Everything is going -to happen there now. - -<ProgramListing> -cd /scratch/joe-bloggs/myfptools-sun4 -</ProgramListing> - -</Para> -</ListItem> -<ListItem> - -<Para> - Prepare for system configuration: - -<ProgramListing> -autoconf -</ProgramListing> - -(You can skip this step if you are starting from a source distribution, -and you already have <Filename>configure</Filename> and <Filename>mk/config.h.in</Filename>.) - -</Para> -</ListItem> -<ListItem> - -<Para> - Do system configuration: - -<ProgramListing> -./configure -</ProgramListing> - - -</Para> -</ListItem> -<ListItem> - -<Para> - Create the file <Filename>mk/build.mk</Filename>, -adding definitions for your desired configuration options. - -<ProgramListing> -emacs mk/build.mk -</ProgramListing> - -</Para> -</ListItem> - -</OrderedList> - -You can make subsequent changes to <Filename>mk/build.mk</Filename> as often -as you like. You do not have to run any further configuration -programs to make these changes take effect. -In theory you should, however, say <Command>gmake clean</Command>, <Command>gmake all</Command>, -because configuration option changes could affect anything—but in practice you are likely to know what's affected. -</Para> - -</Sect2> - -<Sect2> -<Title>Making things</Title> - -<Para> -At this point you have made yourself a fully-configured build tree, -so you are ready to start building real things. -</Para> - -<Para> -The first thing you need to know is that -<Emphasis>you must use GNU <Command>make</Command>, usually called <Command>gmake</Command>, not standard Unix <Command>make</Command></Emphasis>. -If you use standard Unix <Command>make</Command> you will get all sorts of error messages -(but no damage) because the <Literal>fptools</Literal> <Command>Makefiles</Command> use GNU <Command>make</Command>'s facilities -extensively. -</Para> - -</Sect2> - -<Sect2 id="sec-standard-targets"> -<Title>Standard Targets - -<IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm> -<IndexTerm><Primary>makefile targets</Primary></IndexTerm></Title> - -<Para> -In any directory you should be able to make the following: -<VariableList> - -<VarListEntry> -<Term><Literal>boot</Literal>:</Term> -<ListItem> -<Para> -does the one-off preparation required to get ready for the real work. -Notably, it does <Command>gmake depend</Command> in all directories that contain -programs. It also builds the necessary tools for compilation to proceed. -</Para> - -<Para> -You should say <Command>gmake boot</Command> right after configuring your build tree, -but note that this is a one-off, i.e., there's no need to re-do -<Command>gmake boot</Command> if you should re-configure your build tree at a later -stage (no harm caused if you do though). Notably, you should say -<Command>gmake boot</Command> before you say <Command>gmake clean</Command>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>all</Literal>:</Term> -<ListItem> -<Para> -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 <Command>gmake</Command> alone is generally the same as typing <Command>gmake all</Command>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>install</Literal>:</Term> -<ListItem> -<Para> -installs the things built by <Literal>all</Literal>. Where does it -install them? That is specified by -<Filename>mk/config.mk.in</Filename>; you can override it in -<Filename>mk/build.mk</Filename>, or by running -<command>configure</command> with command-line arguments like -<literal>--bindir=/home/simonpj/bin</literal>; see <literal>./configure ---help</literal> for the full details. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>uninstall</Literal>:</Term> -<ListItem> -<Para> -reverses the effect of <Literal>install</Literal>. -</Para> -</ListItem></VarListEntry> - -<VarListEntry> -<Term><Literal>clean</Literal>:</Term> -<ListItem> -<Para> -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 <Command>gmake boot</Command>. -Also preserve files that could be made by building, but normally -aren't because the distribution comes with them.</para> -</ListItem></VarListEntry> - -<varlistentry> -<term><literal>distclean</literal>:</term> -<listitem> -<para>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, <literal>make -distclean</literal> should leave only the files that were in the -distribution.</para> -</listitem> -</varlistentry> - -<varlistentry> -<term><literal>mostlyclean</literal>:</term> -<listitem> -<para>Like <literal>clean</literal>, but may refrain from deleting a -few files that people normally don't want to recompile.</para> -</listitem> -</varlistentry> - -<VarListEntry> -<Term><Literal>maintainer-clean</Literal>:</Term> -<ListItem> -<Para> -Delete everything from the current directory that can be reconstructed -with this Makefile. This typically includes everything deleted by -<literal>distclean</literal>, plus more: C source files produced by -Bison, tags tables, Info files, and so on.</para> - -<para>One exception, however: <literal>make maintainer-clean</literal> -should not delete <filename>configure</filename> even if -<filename>configure</filename> can be remade using a rule in the -<filename>Makefile</filename>. More generally, <literal>make -maintainer-clean</literal> should not delete anything that needs to -exist in order to run <filename>configure</filename> and then begin to -build the program.</para> -</listitem> -</varlistentry> - -<VarListEntry> -<Term><Literal>check</Literal>:</Term> -<ListItem> -<Para> -run the test suite. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -All of these standard targets automatically recurse into -sub-directories. Certain other standard targets do not: -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term><Literal>configure</Literal>:</Term> -<ListItem> -<Para> -is only available in the root directory -<Constant>$(FPTOOLS_TOP)</Constant>; it has been discussed in <XRef LinkEnd="sec-build-config">. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>depend</Literal>:</Term> -<ListItem> -<Para> -make a <Filename>.depend</Filename> file in each directory that needs -it. This <Filename>.depend</Filename> file contains mechanically-generated dependency -information; for example, suppose a directory contains a Haskell -source module <Filename>Foo.lhs</Filename> which imports another module <Literal>Baz</Literal>. -Then the generated <Filename>.depend</Filename> file will contain the dependency: -</Para> - -<Para> - -<ProgramListing> -Foo.o : Baz.hi -</ProgramListing> - -</Para> - -<Para> -which says that the object file <Filename>Foo.o</Filename> depends on the interface file -<Filename>Baz.hi</Filename> generated by compiling module <Literal>Baz</Literal>. The <Filename>.depend</Filename> file is -automatically included by every Makefile. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>binary-dist</Literal>:</Term> -<ListItem> -<Para> -make a binary distribution. This is the -target we use to build the binary distributions of GHC and Happy. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>dist</Literal>:</Term> -<ListItem> -<Para> -make a source distribution. You must be in a -linked build tree to make this target. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -Most <Filename>Makefile</Filename>s have targets other than these. You can discover them by looking in the <Filename>Makefile</Filename> itself. -</Para> - -</Sect2> - -<sect2> -<title>Using a project from the build tree</title> -<para> -If you want to build GHC (say) and just use it direct from the build -tree without doing <literal>make install</literal> first, you can run -the in-place driver script: -<filename>ghc/driver/ghc-inplace</filename>. -</para> - -<para> Do <emphasis>NOT</emphasis> use -<filename>ghc/driver/ghc</filename>, or -<filename>ghc/driver/ghc-4.xx</filename>, 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. -</para> - -<para> -Happy can similarly be run from the build tree, using -<filename>happy/src/happy-inplace</filename>. -</para> -</sect2> - -<Sect2> -<Title>Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm> -<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm> -<IndexTerm><Primary>FAST, makefile -variable</Primary></IndexTerm></Title> - -<Para> -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 <Command>make</Command> is going to rebuild everything -anyway, the following hack may be useful: -</Para> - -<Para> - -<ProgramListing> -gmake FAST=YES -</ProgramListing> - -</Para> - -<Para> -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 <Filename>.depend</Filename> file in the current directory (where -<Command>mkdependHS</Command> and friends store their dependency information). -</Para> - -<Para> -A bit of history: GHC used to come with a <Command>fastmake</Command> 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"). -</Para> - -</Sect2> - -</Sect1> - -<Sect1 id="sec-makefile-arch"> -<Title>The <Filename>Makefile</Filename> architecture -<IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title> - -<Para> -<Command>make</Command> is great if everything works—you type <Command>gmake install</Command> 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. -</Para> - -<Para> -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. -</Para> - -<Sect2> -<Title>A small project</Title> - -<Para> -To get started, let us look at the <Filename>Makefile</Filename> for an imaginary small -<Literal>fptools</Literal> project, <Literal>small</Literal>. Each project in <Literal>fptools</Literal> has its own -directory in <Constant>FPTOOLS_TOP</Constant>, so the <Literal>small</Literal> project will have its own -directory <Constant>FPOOLS_TOP/small/</Constant>. Inside the <Filename>small/</Filename> directory there -will be a <Filename>Makefile</Filename>, looking something like this: -</Para> - -<Para> -<IndexTerm><Primary>Makefile, minimal</Primary></IndexTerm> - -<ProgramListing> -# Makefile for fptools project "small" - -TOP = .. -include $(TOP)/mk/boilerplate.mk - -SRCS = $(wildcard *.lhs) $(wildcard *.c) -HS_PROG = small - -include $(TOP)/target.mk -</ProgramListing> - -</Para> - -<Para> -This <Filename>Makefile</Filename> has three sections: -</Para> - -<Para> - -<OrderedList> -<ListItem> - -<Para> - The first section includes -<FOOTNOTE> - -<Para> -One of the most important -features of GNU <Command>make</Command> that we use is the ability for a <Filename>Makefile</Filename> to -include another named file, very like <Command>cpp</Command>'s <Literal>#include</Literal> -directive. -</Para> - -</FOOTNOTE> - a file of ``boilerplate'' code from the level -above (which in this case will be -<Filename><Constant>FPTOOLS_TOP</Constant>/mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>). As its name -suggests, <Filename>boilerplate.mk</Filename> consists of a large quantity of standard -<Filename>Makefile</Filename> code. We discuss this boilerplate in more detail in -<XRef LinkEnd="sec-boiler">. -<IndexTerm><Primary>include, directive in Makefiles</Primary></IndexTerm> -<IndexTerm><Primary>Makefile inclusion</Primary></IndexTerm> - -Before the <Literal>include</Literal> statement, you must define the <Command>make</Command> variable -<Constant>TOP</Constant><IndexTerm><Primary>TOP</Primary></IndexTerm> to be the directory containing the <Filename>mk</Filename> directory in -which the <Filename>boilerplate.mk</Filename> file is. It is <Emphasis>not</Emphasis> OK to simply say - - -<ProgramListing> -include ../mk/boilerplate.mk # NO NO NO -</ProgramListing> - - -Why? Because the <Filename>boilerplate.mk</Filename> file needs to know where it is, so -that it can, in turn, <Literal>include</Literal> other files. (Unfortunately, when an -<Literal>include</Literal>d file does an <Literal>include</Literal>, the filename is treated relative to -the directory in which <Command>gmake</Command> is being run, not the directory in -which the <Literal>include</Literal>d sits.) In general, <Emphasis>every file <Filename>foo.mk</Filename> -assumes that <Filename><Constant>$(TOP)</Constant>/mk/foo.mk</Filename> refers to itself.</Emphasis> It is up to the -<Filename>Makefile</Filename> doing the <Literal>include</Literal> to ensure this is the case. - -Files intended for inclusion in other <Filename>Makefile</Filename>s are written to have -the following property: <Emphasis>after <Filename>foo.mk</Filename> is <Literal>include</Literal>d, it leaves -<Constant>TOP</Constant> containing the same value as it had just before the <Literal>include</Literal> -statement</Emphasis>. In our example, this invariant guarantees that the -<Literal>include</Literal> for <Filename>target.mk</Filename> will look in the same directory as that for -<Filename>boilerplate.mk</Filename>. - -</Para> -</ListItem> -<ListItem> - -<Para> - The second section defines the following standard <Command>make</Command> -variables: <Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm> (the source files from which is to be -built), and <Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm> (the executable binary to be -built). We will discuss in more detail what the ``standard -variables'' are, and how they affect what happens, in <XRef LinkEnd="sec-targets">. - -The definition for <Constant>SRCS</Constant> uses the useful GNU <Command>make</Command> construct -<Literal>$(wildcard $pat$)</Literal><IndexTerm><Primary>wildcard</Primary></IndexTerm>, which expands to a list of all -the files matching the pattern <Literal>pat</Literal> in the current directory. In -this example, <Constant>SRCS</Constant> is set to the list of all the <Filename>.lhs</Filename> and <Filename>.c</Filename> -files in the directory. (Let's suppose there is one of each, -<Filename>Foo.lhs</Filename> and <Filename>Baz.c</Filename>.) - -</Para> -</ListItem> -<ListItem> - -<Para> - The last section includes a second file of standard code, -called <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm>. It contains the rules that tell -<Command>gmake</Command> how to make the standard targets (<Xref LinkEnd="sec-standard-targets">). Why, you ask, -can't this standard code be part of <Filename>boilerplate.mk</Filename>? Good question. -We discuss the reason later, in <Xref LinkEnd="sec-boiler-arch">. - -You do not <Emphasis>have</Emphasis> to <Literal>include</Literal> the <Filename>target.mk</Filename> 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 <Filename>target.mk</Filename>; the price tag is that you have to understand what -canned rules get enabled, and what they do (<Xref LinkEnd="sec-targets">). - -</Para> -</ListItem> - -</OrderedList> - -</Para> - -<Para> -In our example <Filename>Makefile</Filename>, most of the work is done by the two -<Literal>include</Literal>d files. When you say <Command>gmake all</Command>, the following things -happen: -</Para> - -<Para> - -<ItemizedList> -<ListItem> - -<Para> - <Command>gmake</Command> figures out that the object files are <Filename>Foo.o</Filename> and -<Filename>Baz.o</Filename>. - -</Para> -</ListItem> -<ListItem> - -<Para> - It uses a boilerplate pattern rule to compile <Filename>Foo.lhs</Filename> to -<Filename>Foo.o</Filename> using a Haskell compiler. (Which one? That is set in the -build configuration.) - -</Para> -</ListItem> -<ListItem> - -<Para> - It uses another standard pattern rule to compile <Filename>Baz.c</Filename> to -<Filename>Baz.o</Filename>, using a C compiler. (Ditto.) - -</Para> -</ListItem> -<ListItem> - -<Para> - It links the resulting <Filename>.o</Filename> files together to make <Literal>small</Literal>, -using the Haskell compiler to do the link step. (Why not use <Command>ld</Command>? -Because the Haskell compiler knows what standard libraries to link in. -How did <Command>gmake</Command> know to use the Haskell compiler to do the link, -rather than the C compiler? Because we set the variable <Constant>HS_PROG</Constant> -rather than <Constant>C_PROG</Constant>.) - -</Para> -</ListItem> - -</ItemizedList> - -</Para> - -<Para> -All <Filename>Makefile</Filename>s should follow the above three-section format. -</Para> - -</Sect2> - -<Sect2> -<Title>A larger project</Title> - -<Para> -Larger projects are usually structured into a number of sub-directories, -each of which has its own <Filename>Makefile</Filename>. (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: -</Para> - -<Para> - -<Screen> -$(FPTOOLS_TOP)/ghc/ - Makefile - mk/ - boilerplate.mk - rules.mk - docs/ - Makefile - ...source files for documentation... - driver/ - Makefile - ...source files for driver... - compiler/ - Makefile - parser/...source files for parser... - renamer/...source files for renamer... - ...etc... -</Screen> - -</Para> - -<Para> -The sub-directories <Filename>docs</Filename>, <Filename>driver</Filename>, <Filename>compiler</Filename>, and so on, each -contains a sub-component of GHC, and each has its own <Filename>Makefile</Filename>. -There must also be a <Filename>Makefile</Filename> in <Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc</Filename>. It does most -of its work by recursively invoking <Command>gmake</Command> on the <Filename>Makefile</Filename>s in the -sub-directories. We say that <Filename>ghc/Makefile</Filename> is a <Emphasis>non-leaf -<Filename>Makefile</Filename></Emphasis>, because it does little except organise its children, -while the <Filename>Makefile</Filename>s in the sub-directories are all <Emphasis>leaf -<Filename>Makefile</Filename>s</Emphasis>. (In principle the sub-directories might themselves -contain a non-leaf <Filename>Makefile</Filename> and several sub-sub-directories, but -that does not happen in GHC.) -</Para> - -<Para> -The <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename> is considered a leaf <Filename>Makefile</Filename> even -though the <Filename>ghc/compiler</Filename> has sub-directories, because these sub-directories -do not themselves have <Filename>Makefile</Filename>s in them. They are just used to structure -the collection of modules that make up GHC, but all are managed by the -single <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename>. -</Para> - -<Para> -You will notice that <Filename>ghc/</Filename> also contains a directory <Filename>ghc/mk/</Filename>. It -contains GHC-specific <Filename>Makefile</Filename> boilerplate code. More precisely: -</Para> - -<Para> - -<ItemizedList> -<ListItem> - -<Para> - <Filename>ghc/mk/boilerplate.mk</Filename> is included at the top of -<Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the -sub-directories. It in turn <Literal>include</Literal>s the main boilerplate file -<Filename>mk/boilerplate.mk</Filename>. - - -</Para> -</ListItem> -<ListItem> - -<Para> - <Filename>ghc/mk/target.mk</Filename> is <Literal>include</Literal>d at the bottom of -<Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the -sub-directories. It in turn <Literal>include</Literal>s the file <Filename>mk/target.mk</Filename>. - -</Para> -</ListItem> - -</ItemizedList> - -</Para> - -<Para> -So these two files are the place to look for GHC-wide customisation -of the standard boilerplate. -</Para> - -</Sect2> - -<Sect2 id="sec-boiler-arch"> -<Title>Boilerplate architecture -<IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm> -</Title> - -<Para> -Every <Filename>Makefile</Filename> includes a <Filename>boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> file -at the top, and <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> 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: -</Para> - -<Para> - -<ItemizedList> -<ListItem> - -<Para> - <Filename>boilerplate.mk</Filename> consists of: - -<ItemizedList> -<ListItem> - -<Para> - <Emphasis>Definitions of millions of <Command>make</Command> variables</Emphasis> that -collectively specify the build configuration. Examples: -<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the options to feed to the Haskell compiler; -<Constant>NoFibSubDirs</Constant><IndexTerm><Primary>NoFibSubDirs</Primary></IndexTerm>, the sub-directories to enable within the -<Literal>nofib</Literal> project; <Constant>GhcWithHc</Constant><IndexTerm><Primary>GhcWithHc</Primary></IndexTerm>, the name of the Haskell -compiler to use when compiling GHC in the <Literal>ghc</Literal> project. -</Para> -</ListItem> -<ListItem> - -<Para> -<Emphasis>Standard pattern rules</Emphasis> that tell <Command>gmake</Command> how to construct one -file from another. -</Para> -</ListItem> - -</ItemizedList> - - -<Filename>boilerplate.mk</Filename> needs to be <Literal>include</Literal>d at the <Emphasis>top</Emphasis> -of each <Filename>Makefile</Filename>, so that the user can replace the -boilerplate definitions or pattern rules by simply giving a new -definition or pattern rule in the <Filename>Makefile</Filename>. <Command>gmake</Command> -simply takes the last definition as the definitive one. - -Instead of <Emphasis>replacing</Emphasis> boilerplate definitions, it is also quite -common to <Emphasis>augment</Emphasis> them. For example, a <Filename>Makefile</Filename> might say: - - -<ProgramListing> -SRC_HC_OPTS += -O -</ProgramListing> - - -thereby adding ``<Option>-O</Option>'' to the end of <Constant>SRC_HC_OPTS</Constant><IndexTerm><Primary>SRC_HC_OPTS</Primary></IndexTerm>. - -</Para> -</ListItem> -<ListItem> - -<Para> - <Filename>target.mk</Filename> contains <Command>make</Command> rules for the standard -targets described in <Xref LinkEnd="sec-standard-targets">. These rules are selectively included, -depending on the setting of certain <Command>make</Command> variables. These -variables are usually set in the middle section of the -<Filename>Makefile</Filename> between the two <Literal>include</Literal>s. - -<Filename>target.mk</Filename> must be included at the end (rather than being part of -<Filename>boilerplate.mk</Filename>) for several tiresome reasons: - - -<ItemizedList> -<ListItem> - -<Para> - <Command>gmake</Command> commits target and dependency lists earlier than -it should. For example, <FIlename>target.mk</FIlename> has a rule that looks like -this: - - -<ProgramListing> -$(HS_PROG) : $(OBJS) - $(HC) $(LD_OPTS) $< -o $@ -</ProgramListing> - - -If this rule was in <Filename>boilerplate.mk</Filename> then <Constant>$(HS_PROG)</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm> -and <Constant>$(OBJS)</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm> would not have their final values at the -moment <Command>gmake</Command> encountered the rule. Alas, <Command>gmake</Command> 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 <Filename>Makefile</Filename> itself. - -</Para> -</ListItem> -<ListItem> - -<Para> - 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 <Filename>boilerplate.mk</Filename> would -prevent the user from writing rules for specific targets in specific cases. - -</Para> -</ListItem> -<ListItem> - -<Para> - There are a couple of other reasons I've forgotten, but it doesn't -matter too much. -</Para> -</ListItem> - -</ItemizedList> - -</Para> -</ListItem> - -</ItemizedList> - -</Para> - -</Sect2> - -<Sect2 id="sec-boiler"> -<Title>The main <Filename>mk/boilerplate.mk</Filename> file - -<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm></Title> - -<Para> -If you look at <Filename><Constant>$(FPTOOLS_TOP)</Constant>/mk/boilerplate.mk</Filename> you will find -that it consists of the following sections, each held in a separate -file: -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term><Filename>config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm></Term> -<ListItem> -<Para> -is the build configuration file we -discussed at length in <Xref LinkEnd="sec-build-config">. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Filename>paths.mk</Filename><IndexTerm><Primary>paths.mk</Primary></IndexTerm></Term> -<ListItem> -<Para> -defines <Command>make</Command> variables for -pathnames and file lists. In particular, it gives definitions for: -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term><Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -all source files in the current directory. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -all Haskell source files in the current directory. -It is derived from <Constant>$(SRCS)</Constant>, so if you override <Constant>SRCS</Constant> with a new value -<Constant>HS_SRCS</Constant> will follow suit. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -similarly for C source files. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>HS_OBJS</Constant><IndexTerm><Primary>HS_OBJS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -the <Filename>.o</Filename> files derived from <Constant>$(HS_SRCS)</Constant>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>C_OBJS</Constant><IndexTerm><Primary>C_OBJS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -similarly for <Constant>$(C_SRCS)</Constant>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>OBJS</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -the concatenation of <Constant>$(HS_OBJS)</Constant> and <Constant>$(C_OBJS)</Constant>. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -Any or all of these definitions can easily be overriden by giving new -definitions in your <Filename>Makefile</Filename>. For example, if there are things in -the current directory that look like source files but aren't, then -you'll need to set <Constant>SRCS</Constant> manually in your <Filename>Makefile</Filename>. The other -definitions will then work from this new definition. -</Para> - -<Para> -What, exactly, does <Filename>paths.mk</Filename> consider a ``source file'' to be? It's -based on the file's suffix (e.g. <Filename>.hs</Filename>, <Filename>.lhs</Filename>, <Filename>.c</Filename>, <Filename>.lc</Filename>, etc), but -this is the kind of detail that changes, so rather than -enumerate the source suffices here the best thing to do is to look in -<Filename>paths.mk</Filename>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Filename>opts.mk</Filename><IndexTerm><Primary>opts.mk</Primary></IndexTerm></Term> -<ListItem> -<Para> -defines <Command>make</Command> variables for option -strings to pass to each program. For example, it defines -<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the option strings to pass to the Haskell -compiler. See <Xref LinkEnd="sec-suffix">. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm></Term> -<ListItem> -<Para> -defines standard pattern rules—see <Xref LinkEnd="sec-suffix">. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<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> - -<Sect2 id="sec-suffix"> -<Title>Pattern rules and options - -<IndexTerm><Primary>Pattern rules</Primary></IndexTerm></Title> - -<Para> -The file <Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm> defines standard <Emphasis>pattern -rules</Emphasis> that say how to build one kind of file from another, for -example, how to build a <Filename>.o</Filename> file from a <Filename>.c</Filename> file. (GNU <Command>make</Command>'s -<Emphasis>pattern rules</Emphasis> are more powerful and easier to use than Unix -<Command>make</Command>'s <Emphasis>suffix rules</Emphasis>.) -</Para> - -<Para> -Almost all the rules look something like this: -</Para> - -<Para> - -<ProgramListing> -%.o : %.c - $(RM) $@ - $(CC) $(CC_OPTS) -c $< -o $@ -</ProgramListing> - -</Para> - -<Para> -Here's how to understand the rule. It says that -<Emphasis>something</Emphasis><Filename>.o</Filename> (say <Filename>Foo.o</Filename>) can be built from -<Emphasis>something</Emphasis><Filename>.c</Filename> (<Filename>Foo.c</Filename>), by invoking the C compiler -(path name held in <Constant>$(CC)</Constant>), passing to it the options -<Constant>$(CC_OPTS)</Constant> and the rule's dependent file of the rule -<Literal>$<</Literal> (<Filename>Foo.c</Filename> in this case), and putting the result in -the rule's target <Literal>$@</Literal> (<Filename>Foo.o</Filename> in this case). -</Para> - -<Para> -Every program is held in a <Command>make</Command> variable defined in -<Filename>mk/config.mk</Filename>—look in <Filename>mk/config.mk</Filename> for the -complete list. One important one is the Haskell compiler, which is -called <Constant>$(HC)</Constant>. -</Para> - -<Para> -Every program's options are are held in a <Command>make</Command> variables called -<Constant><prog>_OPTS</Constant>. the <Constant><prog>_OPTS</Constant> variables are defined in -<Filename>mk/opts.mk</Filename>. Almost all of them are defined like this: -</Para> - -<Para> - -<ProgramListing> -CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) -</ProgramListing> - -</Para> - -<Para> -The four variables from which <Constant>CC_OPTS</Constant> is built have the following meaning: -</Para> - -<Para> -<VariableList> - -<VarListEntry> -<Term><Constant>SRC_CC_OPTS</Constant><IndexTerm><Primary>SRC_CC_OPTS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -options passed to all C -compilations. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>WAY_<way>_CC_OPTS</Constant>:</Term> -<ListItem> -<Para> -options passed to C -compilations for way <Literal><way></Literal>. For example, -<Constant>WAY_mp_CC_OPTS</Constant> gives options to pass to the C compiler when -compiling way <Literal>mp</Literal>. The variable <Constant>WAY_CC_OPTS</Constant> holds -options to pass to the C compiler when compiling the standard way. -(<Xref LinkEnd="sec-ways"> dicusses multi-way -compilation.) -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant><module>_CC_OPTS</Constant>:</Term> -<ListItem> -<Para> -options to -pass to the C compiler that are specific to module <Literal><module></Literal>. For example, <Constant>SMap_CC_OPTS</Constant> gives the specific options -to pass to the C compiler when compiling <Filename>SMap.c</Filename>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>EXTRA_CC_OPTS</Constant><IndexTerm><Primary>EXTRA_CC_OPTS</Primary></IndexTerm>:</Term> -<ListItem> -<Para> -extra options to pass to all -C compilations. This is intended for command line use, thus: -</Para> - -<Para> - -<ProgramListing> -gmake libHS.a EXTRA_CC_OPTS="-v" -</ProgramListing> - -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -</Sect2> - -<Sect2 id="sec-targets"> -<Title>The main <Filename>mk/target.mk</Filename> file - -<IndexTerm><Primary>target.mk</Primary></IndexTerm></Title> - -<Para> -<Filename>target.mk</Filename> contains canned rules for all the standard targets -described in <Xref LinkEnd="sec-standard-targets">. It is complicated by the fact that you don't want all of -these rules to be active in every <Filename>Makefile</Filename>. Rather than have a -plethora of tiny files which you can include selectively, there is a -single file, <Filename>target.mk</Filename>, which selectively includes rules based on -whether you have defined certain variables in your <Filename>Makefile</Filename>. 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. -</Para> - -<Para> -<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: -<VariableList> - -<VarListEntry> -<Term><Filename>HS_PROG</Filename><IndexTerm><Primary>HS_PROG</Primary></IndexTerm></Term> -<ListItem> -<Para> -itself. This rule links <Constant>$(OBJS)</Constant> -with the Haskell runtime system to get an executable called -<Constant>$(HS_PROG)</Constant>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>install</Literal><IndexTerm><Primary>install</Primary></IndexTerm></Term> -<ListItem> -<Para> -installs <Constant>$(HS_PROG)</Constant> -in <Constant>$(bindir)</Constant>. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>C_PROG</Constant><IndexTerm><Primary>C_PROG</Primary></IndexTerm></Term> -<ListItem> -<Para> -is similar to <Constant>HS_PROG</Constant>, except that -the link step links <Constant>$(C_OBJS)</Constant> with the C runtime system. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>LIBRARY</Constant><IndexTerm><Primary>LIBRARY</Primary></IndexTerm></Term> -<ListItem> -<Para> -is similar to <Constant>HS_PROG</Constant>, except that -it links <Constant>$(LIB_OBJS)</Constant> to make the library archive <Constant>$(LIBRARY)</Constant>, and -<Literal>install</Literal> installs it in <Constant>$(libdir)</Constant>. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>LIB_DATA</Constant><IndexTerm><Primary>LIB_DATA</Primary></IndexTerm></Term> -<ListItem> -<Para> -… -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>LIB_EXEC</Constant><IndexTerm><Primary>LIB_EXEC</Primary></IndexTerm></Term> -<ListItem> -<Para> -… -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>, <Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>.</Term> -<ListItem> -<Para> -If <Constant>HS_SRCS</Constant> -is defined and non-empty, a rule for the target <Literal>depend</Literal> is included, -which generates dependency information for Haskell programs. -Similarly for <Constant>C_SRCS</Constant>. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -All of these rules are ``double-colon'' rules, thus -</Para> - -<Para> - -<ProgramListing> -install :: $(HS_PROG) - ...how to install it... -</ProgramListing> - -</Para> - -<Para> -GNU <Command>make</Command> 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 <Constant>HS_PROG</Constant> and <Constant>LIBRARY</Constant>, which will -generate two rules for <Literal>install</Literal>. When you type <Command>gmake install</Command> both -rules will be fired, and both the program and the library will be -installed, just as you wanted. -</Para> - -</Sect2> - -<Sect2 id="sec-subdirs"> -<Title>Recursion - -<IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm> -<IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm></Title> - -<Para> -In leaf <Filename>Makefile</Filename>s the variable <Constant>SUBDIRS</Constant><IndexTerm><Primary>SUBDIRS</Primary></IndexTerm> is undefined. -In non-leaf <Filename>Makefile</Filename>s, <Constant>SUBDIRS</Constant> is set to the list of -sub-directories that contain subordinate <Filename>Makefile</Filename>s. <Emphasis>It is up to -you to set <Constant>SUBDIRS</Constant> in the <Filename>Makefile</Filename>.</Emphasis> There is no automation here—<Constant>SUBDIRS</Constant> is too important to automate. -</Para> - -<Para> -When <Constant>SUBDIRS</Constant> is defined, <Filename>target.mk</Filename> includes a rather -neat rule for the standard targets (<Xref LinkEnd="sec-standard-targets"> that simply invokes -<Command>make</Command> recursively in each of the sub-directories. -</Para> - -<Para> -<Emphasis>These recursive invocations are guaranteed to occur in the order -in which the list of directories is specified in <Constant>SUBDIRS</Constant>. </Emphasis>This -guarantee can be important. For example, when you say <Command>gmake boot</Command> it -can be important that the recursive invocation of <Command>make boot</Command> 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. -</Para> - -</Sect2> - -<Sect2 id="sec-ways"> -<Title>Way management - -<IndexTerm><Primary>way management</Primary></IndexTerm></Title> - -<Para> -We sometimes want to build essentially the same system in several -different ``ways''. For example, we want to build GHC's <Literal>Prelude</Literal> -libraries with and without profiling, with and without concurrency, -and so on, so that there is an appropriately-built library archive to -link with when the user compiles his program. It would be possible to -have a completely separate build tree for each such ``way'', but it -would be horribly bureaucratic, especially since often only parts of -the build tree need to be constructed in multiple ways. -</Para> - -<Para> -Instead, the <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> contains some clever magic to -allow you to build several versions of a system; and to control -locally how many versions are built and how they differ. This section -explains the magic. -</Para> - -<Para> -The files for a particular way are distinguished by munging the -suffix. The ``normal way'' is always built, and its files have the -standard suffices <Filename>.o</Filename>, <Filename>.hi</Filename>, and so on. In addition, you can build -one or more extra ways, each distinguished by a <Emphasis>way tag</Emphasis>. The -object files and interface files for one of these extra ways are -distinguished by their suffix. For example, way <Literal>mp</Literal> has files -<Filename>.mp_o</Filename> and <Filename>.mp_hi</Filename>. Library archives have their way tag the other -side of the dot, for boring reasons; thus, <Filename>libHS_mp.a</Filename>. -</Para> - -<Para> -A <Command>make</Command> variable called <Constant>way</Constant> holds the current way tag. <Emphasis><Constant>way</Constant> -is only ever set on the command line of a recursive invocation of -<Command>gmake</Command>.</Emphasis> It is never set inside a <Filename>Makefile</Filename>. So it is a global -constant for any one invocation of <Command>gmake</Command>. Two other <Command>make</Command> -variables, <Constant>way_</Constant> and <Constant>_way</Constant> are immediately derived from <Constant>$(way)</Constant> and -never altered. If <Constant>way</Constant> is not set, then neither are <Constant>way_</Constant> and -<Constant>_way</Constant>, and the invocation of <Command>make</Command> will build the ``normal way''. -If <Constant>way</Constant> is set, then the other two variables are set in sympathy. -For example, if <Constant>$(way)</Constant> is ``<Literal>mp</Literal>'', then <Constant>way_</Constant> is set to ``<Literal>mp_</Literal>'' -and <Constant>_way</Constant> is set to ``<Literal>_mp</Literal>''. These three variables are then used -when constructing file names. -</Para> - -<Para> -So how does <Command>make</Command> ever get recursively invoked with <Constant>way</Constant> set? There -are two ways in which this happens: -</Para> - -<Para> - -<ItemizedList> -<ListItem> - -<Para> - For some (but not all) of the standard targets, when in a leaf -sub-directory, <Command>make</Command> is recursively invoked for each way tag in -<Constant>$(WAYS)</Constant>. You set <Constant>WAYS</Constant> to the list of way tags you want these -targets built for. The mechanism here is very much like the recursive -invocation of <Command>make</Command> in sub-directories (<Xref LinkEnd="sec-subdirs">). - -It is up to you to set <Constant>WAYS</Constant> in your <Filename>Makefile</Filename>; this is how you -control what ways will get built. -</Para> -</ListItem> -<ListItem> - -<Para> - For a useful collection of -targets (such as <Filename>libHS_mp.a</Filename>, <Filename>Foo.mp_o</Filename>) there is a rule which -recursively invokes <Command>make</Command> to make the specified target, setting the -<Constant>way</Constant> variable. So if you say <Command>gmake Foo.mp_o</Command> you should see a -recursive invocation <Command>gmake Foo.mp_o way=mp</Command>, and <Emphasis>in this -recursive invocation the pattern rule for compiling a Haskell file -into a <Filename>.o</Filename> file will match</Emphasis>. The key pattern rules (in <Filename>suffix.mk</Filename>) -look like this: - - -<ProgramListing> -%.$(way_)o : %.lhs - $(HC) $(HC_OPTS) $< -o $@ -</ProgramListing> - - -Neat, eh? -</Para> -</ListItem> - -</ItemizedList> - -</Para> - -</Sect2> - -<Sect2> -<Title>When the canned rule isn't right</Title> - -<Para> -Sometimes the canned rule just doesn't do the right thing. For -example, in the <Literal>nofib</Literal> suite we want the link step to print out -timing information. The thing to do here is <Emphasis>not</Emphasis> to define -<Constant>HS_PROG</Constant> or <Constant>C_PROG</Constant>, and instead define a special purpose rule in -your own <Filename>Makefile</Filename>. By using different variable names you will avoid -the canned rules being included, and conflicting with yours. -</Para> - -</Sect2> - -</Sect1> - -<Sect1 id="sec-booting-from-C"> -<Title>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></Title> - -<Para> -This section is for people trying to get GHC going by using the supplied -intermediate C (<Filename>.hc</Filename>) files. This would probably be -because no binaries have been provided, or because the machine is not ``fully -supported''. -</Para> - -<Para> -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. -</Para> - -<Para> -Assuming you've got them, unpack them on top of a fresh source tree. This -will place matching <Filename>.hc</Filename> files next to the corresponding -Haskell source in the compiler subdirectory <Filename>ghc</Filename> and in -the language package of hslibs (i.e., in <Filename>hslibs/lang</Filename>). -Then follow the `normal' instructions in <Xref -LinkEnd="sec-building-from-source"> for setting up a build tree. -</Para> - -<Para> -The actual build process is fully automated by the -<Filename>hc-build</Filename> script located in the -<Filename>distrib</Filename> directory. If you eventually want to install GHC -into the directory <Filename>INSTALL_DIRECTORY</Filename>, the following -command will execute the whole build process (it won't install yet): -</Para> -<Screen> -foo% distrib/hc-build --prefix=INSTALL_DIRECTORY -</Screen> -<IndexTerm><Primary>--hc-build</Primary></IndexTerm> -<Para> -By default, the installation directory is <Filename>/usr/local</Filename>. If -that is what you want, you may omit the argument to -<Filename>hc-build</Filename>. Generally, any option given to -<Filename>hc-build</Filename> is passed through to the configuration script -<Filename>configure</Filename>. If <Filename>hc-build</Filename> -successfully completes the build process, you can install the resulting -system, as normal, with -</Para> -<Screen> -foo% make install -</Screen> - -<Para> -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.) -</Para> - -</Sect1> - -<Sect1 id="sec-build-pitfalls"> -<Title>Known pitfalls in building Glasgow Haskell - -<IndexTerm><Primary>problems, building</Primary></IndexTerm> -<IndexTerm><Primary>pitfalls, in building</Primary></IndexTerm> -<IndexTerm><Primary>building pitfalls</Primary></IndexTerm></Title> - -<Para> -WARNINGS about pitfalls and known ``problems'': -</Para> - -<Para> - -<OrderedList> -<ListItem> - -<Para> -One difficulty that comes up from time to time is running out of space -in <Filename>/tmp</Filename>. (It is impossible for the configuration stuff to -compensate for the vagaries of different sysadmin approaches to temp -space.) -<IndexTerm><Primary>tmp, running out of space in</Primary></IndexTerm> - -The quickest way around it is <Command>setenv TMPDIR /usr/tmp</Command><IndexTerm><Primary>TMPDIR</Primary></IndexTerm> or -even <Command>setenv TMPDIR .</Command> (or the equivalent incantation with your shell -of choice). - -The best way around it is to say - -<ProgramListing> -export TMPDIR=<dir> -</ProgramListing> - -in your <Filename>build.mk</Filename> file. -Then GHC and the other <Literal>fptools</Literal> programs will use the appropriate directory -in all cases. - - -</Para> -</ListItem> -<ListItem> - -<Para> -In compiling some support-code bits, e.g., in <Filename>ghc/rts/gmp</Filename> and even -in <Filename>ghc/lib</Filename>, you may get a few C-compiler warnings. We think these -are OK. - -</Para> -</ListItem> -<ListItem> - -<Para> -When compiling via C, you'll sometimes get ``warning: assignment from -incompatible pointer type'' out of GCC. Harmless. - -</Para> -</ListItem> -<ListItem> - -<Para> -Similarly, <Command>ar</Command>chiving warning messages like the following are not -a problem: - -<Screen> -ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ -ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ -... -</Screen> - - -</Para> -</ListItem> -<ListItem> - -<Para> - In compiling the compiler proper (in <Filename>compiler/</Filename>), you <Emphasis>may</Emphasis> -get an ``Out of heap space'' error message. These can vary with the -vagaries of different systems, it seems. The solution is simple: - - -<ItemizedList> -<ListItem> - -<Para> - If you're compiling with GHC 4.00 or later, then the -<Emphasis>maximum</Emphasis> heap size must have been reached. This -is somewhat unlikely, since the maximum is set to 64M by default. -Anyway, you can raise it with the -<Option>-optCrts-M<size></Option> flag (add this flag to -<Constant><module>_HC_OPTS</Constant> -<Command>make</Command> variable in the appropriate -<Filename>Makefile</Filename>). - -</Para> -</ListItem> -<ListItem> - -<Para> - For GHC < 4.00, add a suitable <Option>-H</Option> flag to the <Filename>Makefile</Filename>, as -above. - -</Para> -</ListItem> - -</ItemizedList> - - -and try again: <Command>gmake</Command>. (see <Xref LinkEnd="sec-suffix"> for information about -<Constant><module>_HC_OPTS</Constant>.) - -Alternatively, just cut to the chase: - -<Screen> -% cd ghc/compiler -% make EXTRA_HC_OPTS=-optCrts-M128M -</Screen> - - -</Para> -</ListItem> -<ListItem> - -<Para> -If you try to compile some Haskell, and you get errors from GCC about -lots of things from <Filename>/usr/include/math.h</Filename>, then your GCC was -mis-installed. <Command>fixincludes</Command> wasn't run when it should've been. - -As <Command>fixincludes</Command> is now automagically run as part of GCC installation, -this bug also suggests that you have an old GCC. - - -</Para> -</ListItem> -<ListItem> - -<Para> -You <Emphasis>may</Emphasis> need to re-<Command>ranlib</Command><IndexTerm><Primary>ranlib</Primary></IndexTerm> your libraries (on Sun4s). - - -<Screen> -% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 -% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... -? ranlib $i -? # or, on some machines: ar s $i -? end -</Screen> - - -We'd be interested to know if this is still necessary. - - -</Para> -</ListItem> -<ListItem> - -<Para> -GHC's sources go through <Command>cpp</Command> before being compiled, and <Command>cpp</Command> varies -a bit from one Unix to another. One particular gotcha is macro calls -like this: - - -<ProgramListing> -SLIT("Hello, world") -</ProgramListing> - - -Some <Command>cpp</Command>s treat the comma inside the string as separating two macro -arguments, so you get - - -<Screen> -:731: macro `SLIT' used with too many (2) args -</Screen> - - -Alas, <Command>cpp</Command> doesn't tell you the offending file! - -Workaround: don't put weird things in string args to <Command>cpp</Command> macros. -</Para> -</ListItem> - -</OrderedList> - -</Para> - -</Sect1> - - -<Sect1 id="winbuild"><Title>Notes for building under Windows</Title> - -<Para> -This section summarises how to get the utilities you need on your -Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for -installing and running GHC may be found in the user guide. In general, -Win95/Win98 behave the same, and WinNT/Win2k behave the same. It is based -largely on detailed advice from Sigbjørn Finne. You should read the -GHC installation guide sections on Windows (in the user guide) before -continuing to read these notes. -</Para> - - -<Sect2><Title>Installing ssh</Title> - -<ItemizedList> - -<ListItem> -<Para> -Extract the whole of <ULink URL="http://research.microsoft.com/~simonpj/ssh-1_2_26-cygwinb19.tar.gz">the ssh archive</ULink> into your <Filename>C:\</Filename> directory, and use the ``All files'' and ``User folder names'' options in WinZip extract dialogue box. This populates your <Filename>C:\usr\local</Filename> tree. -</Para> -</ListItem> - -<ListItem> -<Para> -Extract <ULink URL="http://research.microsoft.com/~simonpj/cygwinb19.dll.zip">cygwinb19.dll</ULink> into <Filename>/usr/local/bin</Filename>. The current version -of Cywin is b20, but this version of ssh was compiled with b19. -</Para> -</ListItem> - -<ListItem> -<Para> -On a Win2k machine, open up a bash and do -</Para> - -<Screen> -foo$ cd /etc -foo$ mkpasswd -l > passwd -</Screen> - -<Para> -Check that your login entry is on the first line -of that file. If not, move it to the top. It's OK -for 'Administrator' to be the first entry, assuming you are one. -</Para> - -<Para> -However, Win9x doesn't support the calls that <Command>mkpasswd</Command> relies on -(e.g., <Function>NetUserEnum</Function>). If you run <Command>mkpasswd</Command> you -get errors like: -</Para> - -<Screen> -linked to missing export netapi32.dll:NetUserEnum -</Screen> - -<Para> -The passwd file is used -by ssh in a fairly rudimentary manner, so I'd simply -synthesise/copy an existing Unix <Filename>/etc/passwd</Filename>, i.e., create -an <Filename>/etc/passwd</Filename> file containing the line -</Para> - -<Screen> -<login>::500:513:::/bin/sh -</Screen> - -<Para> -where <Literal><login></Literal> is your login id. -</Para> -</ListItem> - -<ListItem> -<Para> -Generate a key, by running <Filename>c:/user/local/bin/ssh-keygen1</Filename>. - This generates a public key in <Filename>.ssh/identity.pub</Filename>, and a - private key in <Filename>.ssh/identity</Filename> -</Para> - -<Para> - In response to the 'Enter passphrase' question, just hit - return (i.e. use an empty passphrase). The passphrase is - a password that protects your private key. But it's a pain - to type this passphrase everytime you use <Command>ssh</Command>, so the best - thing to do is simply to protect your <Filename>.ssh</Filename> directory, and - <Filename>.ssh/identity</Filename> from access by anyone else. To do this - right-click your <Filename>.ssh</Filename> directory, and select Properties. - If you are not on the access control list, add yourself, and - give yourself full permissions (the second panel). - Remove everyone else from the access control list. (Don't - leave them there but deny them access, because 'they' may be - a list that includes you!) -</Para> - -<Para> - If you have problems running <Command>ssh-keygen1</Command> - from within <Command>bash</Command>, start up <Filename>cmd.exe</Filename> and run it as follows: -</Para> - -<Screen> -c:\tmp> set CYGWIN32=tty -c:\tmp> c:/user/local/bin/ssh-keygen1 -</Screen> -</ListItem> - -<ListItem> -<Para> -If you don't have an account on <Literal>cvs.haskell.org</Literal>, send - your <Filename>.ssh/identity.pub</Filename> to the CVS repository administrator - (currently Jeff Lewis <Email>jlewis@cse.ogi.edu</Email>). He will set up - your account. -</Para> - -<Para> - If you do have an account on <Literal>cvs.haskell.org</Literal>, use TeraTerm - to logon to it. Once in, copy the - key that <Command>ssh-keygen1</Command> deposited in <Filename>/.ssh/identity.pub</Filename> into - your <Filename>~/.ssh/authorized_keys</Filename>. Make sure that the new version - of <Filename>authorized_keys</Filename> still has 600 file permission. -</Para> -</ListItem> - -</ItemizedList> - -</Sect2> - - -<Sect2><Title>Installing CVS</Title> - -<ItemizedList> - -<ListItem> -<Para> -Unpack -<ULink URL="http://research.microsoft.com/~simonpj/cvs-1_10-win.zip"> -CVS</ULink> and, following the instructions in the <Filename>README</Filename>, copy the -appropriate files into <Filename>/usr/local/bin</Filename>. -</Para> -</ListItem> - -<ListItem> -<Para> -From the System control panel, -set the following <Emphasis>user</Emphasis> environment variables (see the GHC user guide) -</Para> - -<ItemizedList> -<ListItem> -<Para> -<Constant>HOME</Constant>: points to your home directory. This is where CVS -will look for its <Filename>.cvsrc</Filename> file. -</Para> -</ListItem> - -<ListItem> -<Para> -<Constant>CVS_RSH</Constant>: <Filename>c:/usr/local/bin/ssh1</Filename> -</Para> -</ListItem> - -<ListItem> -<Para> -<Constant>CVSROOT</Constant>: <Literal>:ext:username@cvs.haskell.org:/home/cvs/root</Literal>, -where <Literal>username</Literal> is your userid -</Para> -</ListItem> - -<ListItem> -<Para> -<Constant>CVSEDITOR</Constant>: <Filename>bin/gnuclient.exe</Filename> if you want to use an Emacs buffer for typing in those long commit messages. -</Para> -</ListItem> -</ItemizedList> -</ListItem> - -<ListItem> -<Para> -Put the following in <Filename>$HOME/.cvsrc</Filename>: -</Para> - -<ProgramListing> -checkout -P -release -d -update -P -diff -u -</ProgramListing> - -<Para> -These are the default options for the specified CVS commands, -and represent better defaults than the usual ones. (Feel -free to change them.) -</Para> - -<Para> -Filenames starting with "<Filename>.</Filename>" were illegal in -the 8.3 DOS filesystem, but that restriction should have -been lifted by now (i.e., you're using VFAT or later filesystems.) If -you're still having problems creating it, don't worry; <Filename>.cvsrc</Filename> is entirely -optional. -</Para> -</ListItem> - -<ListItem> -<Para> -Try doing <Command>cvs co fpconfig</Command>. All being well, bytes should -start to trickle through, leaving a directory <Filename>fptools</Filename> -in your current directory. (You can <Command>rm</Command> it if you don't want to keep it.) The following messages appear to be harmless: -</Para> - -<Screen> -setsockopt IPTOS_LOWDELAY: Invalid argument -setsockopt IPTOS_THROUGHPUT: Invalid argument -</Screen> - -<Para> -At this point I found that CVS tried to invoke a little dialogue with -me (along the lines of `do you want to talk to this host'), but -somehow bombed out. This was from a bash shell running in emacs. -I solved this by invoking a Cygnus shell, and running CVS from there. -Once things are dialogue free, it seems to work OK from within emacs. -</Para> -</ListItem> - -<ListItem> -<Para> -If you want to check out part of large tree, proceed as follows: -</Para> - -<ProgramListing> -cvs -f checkout -l papers -cd papers -cvs update cpr -</ProgramListing> - -<Para> -This sequence checks out the <Literal>papers</Literal> module, but none -of its sub-directories. -The "<Option>-l</Option>" flag says not to check out sub-directories. -The "<Option>-f</Option>" flag says not to read the <Filename>.cvsrc</Filename> file -whose <Option>-P</Option> default (don't check out empty directories) is -in this case bogus. -</Para> - -<Para> -The <Command>cvs update</Command> command sucks in a named sub-directory. -</Para> -</ListItem> - -</ItemizedList> - -<Para> -There is a very nice graphical front-end to CVS for Win32 platforms, -with a UI that people will be familiar with, at -<ULink URL="http://www.wincvs.org/">wincvs.org</ULink>. -I have not tried it yet. -</Para> - -</Sect2> - - -<Sect2><Title>Installing autoconf</Title> - -<Para> -Only required if you are doing builds from GHC's sources -checked out from the CVS tree. -</Para> - -<ItemizedList> -<ListItem> -<Para> -Fetch the (standard, Unix) <Command>autoconf</Command> distribution from -<ULink URL="ftp://ftp.gnu.org/gnu/autoconf">ftp.gnu.org</ULink>. -</Para> -</ListItem> -<ListItem> -<Para> -Unpack it into an arbitrary directory. -</Para> -</ListItem> -<ListItem> -<Para> -Make sure that the directory <Filename>/usr/local/bin</Filename> exists. -</Para> -</ListItem> -<ListItem> -<Para> -Say "<Filename>./configure</Filename>". -</Para> -</ListItem> -<ListItem> -<Para> -Now <Command>make install</Command>. This should put <Filename>autoheader</Filename> -and <Filename>autoconf</Filename> in <Filename>/usr/local/bin</Filename>. -</Para> -</ListItem> -</ItemizedList> - -<Para> -<Command>autoheader</Command> doesn't seem to work, but you don't need it -for GHC. -</Para> - -</Sect2> - - -<Sect2><Title>Building GHC</Title> - -<ItemizedList> - -<ListItem> -<Para> -In the <Filename>./configure</Filename> output, ignore -"<Literal> -checking whether #! works in shell scripts... -./configure: ./conftest: No such file or directory</Literal>", -and "<Literal>not updating unwritable cache ./config.cache</Literal>". -Nobody knows why these happen, but they seem to be harmless. -</Para> -</ListItem> - -<ListItem> -<Para> -You have to run <Command>autoconf</Command> both in <Filename>fptools</Filename> -and in <Filename>fptools/ghc</Filename>. If you omit the latter step you'll -get an error when you run <Filename>./configure</Filename>: -</Para> - -<Screen> -...lots of stuff... -creating mk/config.h -mk/config.h is unchanged -configuring in ghc -running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. -./configure: ./configure: No such file or directory -configure: error: ./configure failed for ghc -</Screen> -</ListItem> - -<ListItem> -<Para> -You need <Filename>ghc</Filename> to be in your <Constant>PATH</Constant> before you run -<Command>configure</Command>. The default GHC InstallShield creates only -<Filename>ghc-4.08</Filename>, so you may need to duplicate this file as <Filename>ghc</Filename> -in the same directory, in order that <Command>configure</Command> will see it (or -just rename <Filename>ghc-4.08</Filename> to <Filename>ghc</Filename>. -And make sure that the directory is in your path. -</Para> -</ListItem> - -</ItemizedList> - -</Sect2> - -</Sect1> - -</Article> |