<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-<Article>
+<Article id="building-guide">
<ArtHeader>
</Sect1>
-<Sect1>
+<Sect1 id="sec-build-checks">
<Title>Things to check before you start typing</Title>
<Para>
<ListItem>
<Para>
-<IndexTerm><Primary>Disk space needed</Primary></IndexTerm>Disk space needed: About 30MB (five hamburgers' worth) of disk space
-for the most basic binary distribution of GHC; more for some
-platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
-Haskell libraries) might take you to 8–10 hamburgers.
-
-You'll need over 100MB (say, 20 hamburgers' worth) if you need to
-build the basic stuff from scratch.
-
-
-All of the above are <Emphasis>estimates</Emphasis> of disk-space needs. (I don't yet
-know the disk requirements for the non-GHC tools).
-
+<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>
<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>
<ListItem>
<Para>
-All our documentation is written in SGML, using the DocBook DTD and
-processed using the <ULink
-URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook
-tools</ULink>, which is the most shrink-wrapped SGML suite that we
-could find. You need all the RPMs except for psgml (i.e. docbook, jade, jadetex, sgmlcommon and stylesheets). Unfortunately, it's only packaged as RPMs. You can use it to generate HTML, DVI (and hence PDF and Postscript) and RTF from any DocBook source file (including this manual). N.B. The <Emphasis>Cygnus</Emphasis> version of the tools is assumed. Others, such as the SuSE version, may not work.
+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>
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).
+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>
reverses the effect of <Literal>install</Literal>.
</Para>
</ListItem></VarListEntry>
+
<VarListEntry>
<Term><Literal>clean</Literal>:</Term>
<ListItem>
<Para>
-remove all easily-rebuilt files.
-</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>veryclean</Literal>:</Term>
+<Term><Literal>maintainer-clean</Literal>:</Term>
<ListItem>
<Para>
-remove all files that can be rebuilt at all.
-There's a danger here that you may remove a file that needs a more
-obscure utility to rebuild it (especially if you started from a source
-distribution).
-</Para>
-</ListItem></VarListEntry>
+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>
</Sect1>
-<Sect1>
+<Sect1 id="sec-makefile-arch">
<Title>The <Filename>Makefile</Filename> architecture
<IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
<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
+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.
+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.
-Then follow the `normal' instructions in <Xref LinkEnd="sec-building-from-source"> for setting
-up a build tree. When you invoke the configure script, you'll have
-to tell the script about your intentions:
+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% ./configure --enable-hc-boot
+foo% distrib/hc-build --prefix=INSTALL_DIRECTORY
</Screen>
-
-<IndexTerm><Primary>--enable-hc-boot</Primary></IndexTerm>
-<IndexTerm><Primary>--disable-hc-boot</Primary></IndexTerm>
-</Para>
-
+<IndexTerm><Primary>--hc-build</Primary></IndexTerm>
<Para>
-Assuming it configures OK and you don't need to create <Filename>mk/build.mk</Filename>
-for any other purposes, the next step is to proceed with a <Command>make boot</Command>
-followed by <Command>make all</Command>. At the successful completion of <Command>make all</Command>,
-you should end up with a binary of the compiler proper,
-<Filename>ghc/compiler/hsc</Filename>, plus archives (but no <Filename>.hi</Filename> files!) of the prelude
-libraries. To generate the Prelude interface files (and test drive the
-bootstrapped compiler), re-run the <Command>configure</Command> script, but this time
-without the <Option>--enable-hc-boot</Option> option. After that re-create the
-contents of <Filename>ghc/lib</Filename>:
+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>
-
-<Para>
-
<Screen>
-foo% ./configure
- ....
-foo% cd ghc/lib
-foo% make clean
-foo% make boot
-foo% make all
+foo% make install
</Screen>
-</Para>
-
<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
<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.
+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>
<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.05</Filename>, so you may need to duplicate this file as <Filename>ghc</Filename>
+<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.05</Filename> to <Filename>ghc</Filename>.
+just rename <Filename>ghc-4.08</Filename> to <Filename>ghc</Filename>.
And make sure that the directory is in your path.
</Para>
</ListItem>
-<ListItem>
-<Para>
-Compile <Command>happy</Command> and <Command>ghc</Command>
-with <Option>-static</Option>. To do this, set
-</Para>
-
-<ProgramListing>
-GhcHcOpts=-static
-HappyHcOpts=-static
-</ProgramListing>
-
-<Para>
-in your <Filename>build.mk</Filename> file.
-[Actually, I successfully compiled Happy without <Option>-static</Option> on Win2k, but not GHC.]
-</Para>
-</ListItem>
-
</ItemizedList>
</Sect2>
projects / ghc-hetmet.git / blobdiff