% Building and installing the Glasgow Functional Programming Tools Suite
%
-% Version 2.02
-% Feb 1997
+% Version 2.08
+% July 1997
\begin{onlystandalone}
\documentstyle[11pt,literate]{article}
\begin{document}
\title{Building and installing the Glasgow Functional Programming Tools Suite\\
-Version~2.02}
+Version~2.08}
\author{The GHC Team\\
Department of Computing Science\\
University of Glasgow\\
programs from the Glasgow @fptools@ suite (as distinct from those
who merely want to {\em run} them).
-The whole install-and-make system has been completely re-done
-between GHC 2.01 and 2.02, so it will be worth your while to re-read this guide
-even if you have done so before.
+The whole install-and-make system was completely re-done between GHC
+2.01 and 2.02, so it will be worth your while to re-read this guide
+even if you have read earlier versions.
\section{Getting the Glasgow @fptools@ suite}
\begin{description}
\item[Binary distribution.] If your only purpose is to install
some of the @fptools@ suite then the easiest thing to do is to
-get a binary distribution. In the binary distribution everything is
+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. {\em Need pointer to info about doing binary installation.}
-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 havn't yet ported the
-suite to your architecture, in which case you are considerably worse off.
+A binary distribution may not work for you for two reasons. First, we
+may not have built the suite for the particular architecture/OS
+platform you want. That may be due to lack of time and energy (in
+which case you can get a source distribution and build from it; see
+below). Alternatively, it may be because we haven't yet ported the
+suite to your architecture, in which case you are considerably worse
+off.
The second reason a binary distribution may not be what you want is
if you want to read or modify the souce code.
\item[Source distribution.]
-You have a supported
-platform, but (a)~you like the warm fuzzy feeling of compiling things
-yourself; (b)~you want to build something ``extra''---e.g., a set of
-libraries with strictness-analysis turned off; or (c)~you want to hack
-on GHC yourself.
+You have a supported platform, but (a)~you like the warm fuzzy feeling
+of compiling things yourself; (b)~you want to build something
+``extra''---e.g., a set of libraries with strictness-analysis turned
+off; or (c)~you want to hack on GHC yourself.
A source distribution contains complete sources for the @fptools@ suite.
Not only that, but the more awkward machine-independent steps are done
-for you. For example, if you don't have @flex@ you'll it convenient that
-the source distribution contains the result of running @flex@ on the
-lexical analyser specification. If you don't want to alter the lexical
-analyser then this saves you having to find and install @flex@.
-You will still need a working version of GHC on your machine in order to
-compile (most of) the sources, however.
-
+for you. For example, if you don't have @flex@ you'll find it
+convenient that the source distribution contains the result of running
+@flex@ on the lexical analyser specification. If you don't want to
+alter the lexical analyser then this saves you having to find and
+install @flex@. You will still need a working version of GHC on your
+machine in order to compile (most of) the sources, however.
+
+We make source distributions more frequently than binary
+distributions; a release that comes with pre-compiled binaries
+is considered a major release, i.e., a release that we have some
+confidence will work well by having tested it (more) thoroughly.
+
+Source-only distributions are either bugfix releases or snapshots of
+current state of development. The release has undergone some testing.
+Source releases of 2.0x can be compiled up using 2.07 (or subsequent
+bugfix releases) or the Good Old Compiler, GHC~0.29. Compiling with
+0.29 is recommended if you're a performance junkie, as 0.29 (still)
+generates zippier code, but GHC~2.0x is catching up.
\item[Build GHC from intermediate C \tr{.hc} files:]
-You need a working GHC to use a source distribution. What if you don't have a working GHC?
-Then you have no choice but to ``bootstrap'' up from the
-intermediate C (\tr{.hc}) files that we provide.
+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 (\tr{.hc}) files that we provide.
Building GHC on an unsupported platform falls into this category.
Please see \sectionref{booting-from-C}.
-NB: For GHC~2.01, bootstrapping from \tr{.hc} files means you will get
-an all-2.01 system---possibly unduly slow. Building with GHC~0.29
-will get you a faster compiler...
-
Once you have built GHC, you can build the other Glasgow tools with
it.
-In theory, you can build GHC with another Haskell compiler (e.g.,
-HBC). We havn't tried to do this for ages and it almost certainly
-doesn't work any more.
+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).
\item[The CVS repository.]
+
We make source distributions at the same time as binary distributions;
-i.e. infrequently. They should, however, be pretty throughly tested.
+i.e. infrequently. They should, however, be pretty thoroughly tested.
If you want more up-to-the minute (but less tested) source code then you
need to get access to our CVS repository.
-All the @fptools@ source code is held in a CVS repository.
-CVS is a pretty good source-code control system, and best of all it works over the network.
+All the @fptools@ source code is held in a CVS repository. CVS is a
+pretty good source-code control system, and best of all it works over
+the network.
-The repository holds source code only. It holds no mechanically generated
-files at all. So if you check out a source tree from CVS you will need
-to install every utility so that you can build all the derived files
-from scratch.
+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.
Giving you access to the repository entails some systems administration
at our end; and we are a bit nervous about being submerged in bug reports
\end{description}
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.
-
+distribution or the CVS repository) then you need to read all of this
+manual in detail.
%************************************************************************
%* *
You'll need over 100MB (say, 20 hamburgers' worth) if you need to
build the basic stuff from scratch.
-I don't yet know the disk requirements for the non-GHC tools.
-All of the above are {\em estimates} of disk-space needs.
+All of the above are {\em estimates} of disk-space needs.(I don't yet
+know the disk requirements for the non-GHC tools).
\item
Use an appropriate machine, compilers, and things.
-SPARC boxes and DEC Alphas running OSF/1 are fully supported.
-Linux, MIPS, and HP boxes are in pretty good shape.
-\Sectionref{port-info} gives the full run-down on ports or lack
-thereof.
+SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
+or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
+in pretty good shape. \Sectionref{port-info} gives the full run-down
+on ports or lack thereof.
\item
Be sure that the ``pre-supposed'' utilities are installed.
For GHC, please see the bug-reporting section of the User's guide
(separate document), to maximise the usefulness of your report.
-If in doubt, please send a message to
-\tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
+If in doubt, please send a message to \tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
\end{enumerate}
%************************************************************************
%* *
-\section[port-info]{What machines the Glasgow tools, version~2.01, run on}
+\section[port-info]{What machines the Glasgow tools run on}
\index{ports, GHC}
\index{GHC ports}
\index{supported platforms}
architecture/manufacturer/operating-system combination,
such as @sparc-sun-solaris2.5.1@. Other common ones are
@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
-@i386-unknown-solaris2@, @i386-unknown-freebsd@,
-@m68k-sun-sunos4@, @mips-sgi-irix5@,
-@sparc-sun-sunos4@, @sparc-sun-solaris2@.
+@i386-unknown-solaris2@, @i386-unknown-freebsd@, @i386-unknown-cygwin32@,
+@m68k-sun-sunos4@, @mips-sgi-irix5@, @sparc-sun-sunos4@,
+@sparc-sun-solaris2@, @powerpc-ibm-aix@.
Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
work on all machines for which basic Haskell compiling is supported.
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.
+(``Unregisterised'' is so terrible that we won't say more about it).
We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas
running OSF/1~V2.0, so those are the ``fully-supported'' platforms,
compilations. The native-code generator for iX86 platforms (e.g.,
Linux ELF) is {\em nearly} working; but is not turned on by default.
-Here's everything that's known about GHC ports, as of 2.01. We
-identify platforms by their ``canonical GNU-style'' names.
+Here's everything that's known about GHC ports. We identify platforms
+by their ``canonical'' CPU/Manufacturer/OS triple.
Note that some ports are fussy about which GCC version you use; or
require GAS; or ...
%-------------------------------------------------------------------
\item[\tr{i386-*-linux} (PCs running Linux---ELF format):]
\index{i386-*-linux: registerised port}
-GHC~2.01 works registerised.
+GHC works registerised.
You {\em must} have GCC 2.7.x or later.
The iX86 native-code generator is {\em nearly} there, but it
isn't turned on by default.
%-------------------------------------------------------------------
\item[\tr{i386-*-freebsd} (PCs running FreeBSD 2.2 or higher, and
NetBSD/OpenBSD using FreeBSD emulation):] \index{i386-*-freebsd:
-registerised port} GHC~2.01 works registerised. Supports same set of
+registerised port} GHC works registerised. Supports same set of
bundles as the above.
\index{i386-*-freebsd: profiling---yes}
%-------------------------------------------------------------------
\item[\tr{mips-sgi-irix5}:]
\index{mips-sgi-irix5: registerised port}
-GHC~2.01 works registerised (no native-code generator).
+GHC works registerised (no native-code generator).
I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
was built with \tr{--with-gnu-as}; turns out that is important!
\index{mips-sgi-irix5: profiling---maybe}
%-------------------------------------------------------------------
+\item[\tr{mips-sgi-irix6}:]
+\index{mips-sgi-irix6: registerised port}
+Thanks to the fine efforts of Tomasz Cholewo
+\tr{<tjchol01@mecca.spd.louisville.edu>}, GHC works registerised
+(no native code generator) under IRIX 6.2 and 6.3. Depends on having
+specially tweaked version of gcc-2.7.2 around, which can be downloaded
+from
+
+\begin{verbatim}
+ http://mecca.spd.louisville.edu/~tjchol01/software/
+\end{verbatim}
+
+Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
+\index{mips-sgi-irix6: concurrent---maybe}
+\index{mips-sgi-irix6: parallel---maybe}
+\index{mips-sgi-irix6: profiling---yes}
+
+%-------------------------------------------------------------------
+\item[\tr{powerpc-ibm-aix}:]
+\index{powerpc-ibm-aix: registerised port}
+GHC works registerised (no native-code generator..yet).
+I suspect 2.7.x is what you need together with this.
+
+Concurrent/Parallel Haskell probably don't work (yet).
+Profiling might work, but it is untested.
+\index{mips-sgi-irix5: concurrent---no}
+\index{mips-sgi-irix5: parallel---no}
+\index{mips-sgi-irix5: profiling---maybe}
+
+%-------------------------------------------------------------------
\item[\tr{m68k-apple-macos7} (Mac, using MPW):]
\index{m68k-apple-macos7: historically ported}
Once upon a time, David Wright in Tasmania has actually
%-------------------------------------------------------------------
\item[\tr{m68k-next-nextstep3}:]
\index{m68k-next-nextstep3: historically ported}
-Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19.
+Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29.
There's probably a little bit-rot since then, but otherwise it should
-still be fine. Had a report that things were basically OK at 0.22.
+still be fine.
Concurrent/Parallel Haskell probably won't work (yet).
\index{m68k-next-nextstep3: concurrent---no}
%-------------------------------------------------------------------
\item[\tr{m68k-sun-sunos4} (Sun3):]
\index{m68k-sun-sunos4: registerised port}
-GHC~2.01 hasn't been tried on a Sun3. GHC~0.26 worked registerised.
+GHC 2.0x hasn't been tried on a Sun3. GHC~0.26 worked registerised.
No native-code generator.
Concurrent/Parallel Haskell probably don't work (yet).
Suppose that you untar a binary-distribution bundle, thus:
\begin{verbatim}
% cd /your/scratch/space
- % gunzip < ghc-2.02-sun-sparc-solaris2.tar.gz | tar xvf -
+ % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
\end{verbatim}
Then you should find a single directory, @fptools@, with the following
structure:
directly by the user. These are the files that must end up in your path.
\item[@lib/<platform>@] contains platform-specific support files for the installation.
Typically there is a subdirectory for each @fptools@ project, whose name is
-the name of the project with its version number.
-For example, for GHC 2.02 there would be a sub-directory @ghc-2.02/@.
+the name of the project with its version number. For example, for GHC
+there would be a sub-directory @ghc-x.xx/@ where @x.xx@ is the version
+number of GHC in the bundle.
These sub-directories have the following general structure:
\begin{description}
ones from different releases or platforms) into a single @fptools@ directory:
\begin{verbatim}
% cd /your/scratch/space
- % gunzip < ghc-2.02-sun-sparc-solaris2.tar.gz | tar xvf -
- % gunzip < happy-1.09-sun-sparc-sunos4.tar.gz | tar xvf -
+ % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
+ % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -
\end{verbatim}
When you do multiple unpacks like this, the top level @Makefile@, @README@,
and @INSTALL@ get overwritten each time. That's fine -- they should be the same.
That should convert @Makefile.in@ to @Makefile@.
You can now either start using the tools {\em in-situ} without going
-through any installation process, just type @make config@ to set the
-tools up for this (you have to be in the @fptools@ directory). You'll
-also want to add the path which @make@ echoes to your @PATH@
-environment variable. This option is useful if you simply want to try
-out the package or you don't have the necessary priviledges (or
+through any installation process, just type @make in-place@ to set the
+tools up for this (you have to be in the @fptools@ directory for
+this). You'll also want to add the path which @make@ will now echo to
+your @PATH@ environment variable. This option is useful if you simply want
+to try out the package and/or you don't have the necessary priviledges (or
inclination) to properly install the tools locally. Note that if you
do decide to install the package `properly' at a later date, you have
-to go through the installation steps that
-follows.
+to go through the installation steps that follows.
To install an @fptools@ package, you'll have to do the following:
\end{enumerate}
When installing the user-invokable binaries, this installation
-procedure will install, say, @GHC@ version 2.02 as @ghc-2.02@. It
-will also make a link (in the binary installation directory) from
-@ghc@ to @ghc-2.02@. If you install multiple versions of GHC then the
-last one ``wins'', and ``@ghc@'' will invoke the last one installed.
-You can change this manually if you want. But regardless, @ghc-2.02@
-should always invoke @GHC@ version 2.02.
+procedure will install GHC as @ghc-x.xx@ where @x.xx@ is the version
+number of GHC. It will also make a link (in the binary installation
+directory) from @ghc@ to @ghc-x.xx@. If you install multiple versions
+of GHC then the last one ``wins'', and ``@ghc@'' will invoke the last
+one installed. You can change this manually if you want. But
+regardless, @ghc-x.xx@ should always invoke GHC version @x.xx@.
\subsection{What bundles there are}
There are plenty of ``non-basic'' GHC bundles. The files for them are
-called \tr{ghc-2.01-<bundle>-<platform>.tar.gz}, where the
+called \tr{ghc-x.xx-<bundle>-<platform>.tar.gz}, where the
\tr{<platform>} is as above, and \tr{<bundle>} is one of these:
\begin{description}
\item[\tr{prof}:] Profiling with cost-centres. You probably want this.
First, give yourself a convenient way to execute the driver script
\tr{ghc/driver/ghc}, perhaps something like...
\begin{verbatim}
-% ln -s /local/src/ghc-2.01/ghc/driver/ghc ~/bin/alpha/ghc
+% ln -s /local/src/ghc-x.xx/ghc/driver/ghc ~/bin/alpha/ghc
% rehash
\end{verbatim}
\item[GNU C (\tr{gcc}):]
\index{pre-supposed: GCC (GNU C compiler)}
\index{GCC (GNU C compiler), pre-supposed}
-The current version is 2.7.2. It has a bug that it ticked if you
-compile the @gmp@ library without the @-O@ flag. So the Makefile in
-there has the @-O@ flag switched on! Otherwise, 2.7.2 has no problems that we know of.
+The current version is 2.7.2.
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.
\index{PVM3 (Parallel Virtual Machine), pre-supposed}
PVM is the Parallel Virtual Machine on which Parallel Haskell programs
run. (You only need this if you plan to run Parallel Haskell.
-Concurent Haskell, which runs concurrent threads on a uniprocessor)
+Concurent Haskell, which runs concurrent threads on a uniprocessor
doesn't need it.)
Underneath PVM, you can have (for example) a network of
workstations (slow) or a multiprocessor box (faster).
-The current version of PVM is 3.3.11; we use 3.3.7. It is readily available on
-the net; I think I got it from \tr{research.att.com}, in \tr{netlib}.
+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 \tr{research.att.com}, in
+\tr{netlib}.
A PVM installation is slightly quirky, but easy to do. Just follow
the \tr{Readme} instructions.
This is a quite-a-bit-better-than-Lex lexer. Used in the
literate-programming stuff. You won't need it unless you're hacking
on some of our more obscure stuff.
+On our machines, the version in @/bin@ doesn't work; you need the
+GNU version. Find out by saying @flex --version@ (our current version
+is 2.5.3, but maybe earlier ones will work). If it doesn't know about
+the @--version@ flag, it ain't the right @flex@.
\item[Yacc:]
\index{pre-supposed: non-worthless Yacc}
\index{sed, pre-supposed}
You need a working @sed@ if you are going to build from sources.
The build-configuration stuff needs it.
-GNU sed version 2.0.4 is no good! It has a bug in it that is tickled by the
-build-configuration. 2.0.5 is ok. Others are probably ok too
+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..)
\end{description}
they are useful for all the others:
\begin{itemize}
\item @glafp-utils@ contains several utilities which aren't
-particularly Glasgow-ish, but Occasionally Indispensable.
-
+particularly Glasgow-ish, but Occasionally Indispensable. Like
+@lndir@ for creating symbolic link trees.
\item @literate@ contains the Glasgow-built tools for generating
documentation. (The unoriginal idea is to be able to generate @latex@, @info@,
-
%************************************************************************
%* *
-\section{Building from source}
+\section[building-from-source]{Building from source}
+\index{Building from source}
%* *
%************************************************************************
software, and lay hands on them gently when they don't work.
\subsection{Your source tree}
+\label{source-tree}
The source code is held in your {\em source tree}.
The root directory of your source tree {\em must}
\item @mk/@: the directory that contains the
main Makefile code, shared by all the
@fptools@ software.
-\item @configure.in@: a file that tells the GNU configuration
-tools what @fptools@ needs to know about the host platform and
-operating system.
+\item @configure.in@, @config.sub@, @config.guess@:
+these files support the configuration process.
+\item @install-sh@.
\end{itemize}
All the other directories are individual {\em projects} of the
@fptools@ system --- for example, the Glasgow Haskell Compiler (@ghc@),
a version of @happy@ that's already installed on your system, or
grab a binary distribution of @happy@ and install it.
-The important thing to remember is that even if you want only
-one project (@happy@, say), you must have a source tree
-whose root directory contains @Makefile@,
-@mk/@, @configure.in@, and the project(s) you
-want (@happy/@ in this case). You cannot get by with
+The important thing to remember is that even if you want only one
+project (@happy@, say), you must have a source tree whose root
+directory contains @Makefile@, @mk/@, @configure.in@, and the
+project(s) you want (@happy/@ in this case). You cannot get by with
just the @happy/@ directory.
\subsection{Build trees}
It's very desirable to share a single copy of the source code among
all these builds.
-So for every source tree we have zero or more {\em build trees}.
-Each build tree is initially an exact copy of the source tree,
-except that each file is a symbolic link to the source file,
-rather than being a copy of the source file. There are ``standard''
-Unix utilities that make such copies, so standard that they go by
-different names: @lndir@, @mkshadowdir@ are two (If you don't have
-either, the source distribution includes sources for the \tr{X11}
-\tr{lndir} --- check out \tr{fptools/glafp-utils/lndir} ).
-
-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 -- Section~\ref{sect_build-config})
-{\em absolutely
+So for every source tree we have zero or more {\em build trees}. Each
+build tree is initially an exact copy of the source tree, except that
+each file is a symbolic link to the source file, rather than being a
+copy of the source file. There are ``standard'' Unix utilities that
+make such copies, so standard that they go by different names:
+@lndir@, @mkshadowdir@ are two (If you don't have either, the source
+distribution includes sources for the \tr{X11} \tr{lndir} --- check
+out \tr{fptools/glafp-utils/lndir} ).
+
+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 -- Section~\ref{sect_build-config}) {\em absolutely
everything in the build tree is either a symbolic link to the source
-tree, or else is mechanically generated}. It should be perfectly
-OK for your build tree to vanish overnight; an hour or two compiling
-and you're on the road again.
+tree, or else is mechanically generated}. It should be perfectly OK
+for your build tree to vanish overnight; an hour or two compiling and
+you're on the road again.
You need to be a bit careful, though, that any new files you create
(if you do any development work) are in the source tree, not a build tree!
actually all you've done is edit the build-tree copy. More commonly
you do want to edit the source file.)
-Like the source tree, the top level of your build tree must (a linked copy of)
-the root directory of the @fptools@ suite.
-Inside Makefiles, the root of your build tree is called @$(FPTOOLS_TOP)@.
-In the rest of this document path names are relative to @$(FPTOOLS_TOP)@
-unless otherwise stated. For example, the file @ghc/mk/target.mk@ is
+Like the source tree, the top level of your build tree must (a linked
+copy of) the root directory of the @fptools@ suite. Inside Makefiles,
+the root of your build tree is called @$(FPTOOLS_TOP)@. In the rest
+of this document path names are relative to @$(FPTOOLS_TOP)@ unless
+otherwise stated. For example, the file @ghc/mk/target.mk@ is
actually @$(FPTOOLS_TOP)/ghc/mk/target.mk@.
\subsection{Getting the build you want}
\label{sect_build-config}
-When you build @fptools@ you will be compiling code
-on a particular {\em host platform},
-to run on a particular {\em target platform} (usually the same
-as the host platform)\index{platform}. The difficulty is
-that there are minor differences between different platforms;
-minor, but enough that the code needs to be a bit different
-for each. There are some big differences too: for
-a different architecture we need to build GHC with a different
-native-code generator.
+When you build @fptools@ you will be compiling code on a particular
+{\em host platform}, to run on a particular {\em target platform}
+(usually the same as the host platform)\index{platform}. The
+difficulty is that there are minor differences between different
+platforms; minor, but enough that the code needs to be a bit different
+for each. There are some big differences too: for a different
+architecture we need to build GHC with a different native-code
+generator.
There are also knobs you can turn to control how the @fptools@
-software is built. For example, you might want to build GHC
-optimised (so that it runs fast) or unoptimised (so that you can
-compile it fast after you've modified it.
-Or, you might want to compile it with debugging on (so that
-extra consistency-checking code gets included) or off. And so on.
+software is built. For example, you might want to build GHC optimised
+(so that it runs fast) or unoptimised (so that you can compile it fast
+after you've modified it. Or, you might want to compile it with
+debugging on (so that extra consistency-checking code gets included)
+or off. And so on.
All of this stuff is called the {\em configuration} of your build.
You set the configuration using an exciting three-step process.
\begin{description}
-\item[Step 1: get ready for configuration.]
-Change directory to @$(FPTOOLS)@ and issue the following two commands (with no arguments):
-\begin{enumerate}
-\item @autoconf@. This GNU program
-converts @$(FPTOOLS)/configure.in@ to a shell script
-called @$(FPTOOLS)/configure@.
-\item @autoheader@. This second GNU program converts
-@$(FPTOOLS)/configure.in@ to @$(FPTOOLS)/mk/config.h.in@.
-\end{enumerate}
+\item[Step 1: get ready for configuration.] Change directory to
+@$(FPTOOLS)@ and issue the command @autoconf@ (with no
+arguments). This GNU program converts @$(FPTOOLS)/configure.in@ to a
+shell script called @$(FPTOOLS)/configure@.
+
Both these steps are completely platform-independent; they just mean
that the human-written file (@configure.in@) can be short, although
-the resulting shell script, @configure@, and @mk/config.h.in@, are long.
+the resulting shell script, @configure@, and @mk/config.h.in@, are
+long.
-In case you don't have @autoconf@ and @autoheader@ we distribute
-the results, @configure@, and @mk/config.h.in@, with the source distribution.
-They aren't kept in the repository, though.
+In case you don't have @autoconf@ we distribute the results,
+@configure@, and @mk/config.h.in@, with the source distribution. They
+aren't kept in the repository, though.
\item[Step 2: system configuration.]
Runs the newly-created @configure@ script, thus:
The latter is @#include@d by various C programs, which
can thereby make use of configuration information.
\end{itemize}
-
+@configure@ caches the results of its run in @config.cache@.
+Quite often you don't want that; you're running @configure@ a second time
+because something has changed. In that case, simply delete @config.cache@.
\item[Step 3: build configuration.] Next, you say how this build
of @fptools@ is to differ from the standard defaults by creating a new
For example, @config.mk.in@ contains the definition:
\begin{verbatim}
- ProjectsToBuild = glafp-utils literate ghc hslibs
+ ProjectsToBuild = glafp-utils literate happy ghc hslibs
\end{verbatim}
The accompanying comment explains that this is the list of enabled
projects; that is, if (after configuring) you type @gmake all@
in @FPTOOLS_TOP@ three specified projects will be made.
-If you want to add @happy@, you can add this line to @build.mk@:
+If you want to add @green-card@, you can add this line to @build.mk@:
\begin{verbatim}
- ProjectsToBuild += happy
+ ProjectsToBuild += green-card
\end{verbatim}
or, if you prefer,
\begin{verbatim}
- ProjectsToBuild = glafp-utils literate ghc hslibs happy
+ ProjectsToBuild = glafp-utils literate happy ghc hslibs green-card
\end{verbatim}
(GNU @make@ allows existing definitions to have new text appended using
the ``@+=@'' operator, which is quite a convenient feature.)
You do not {\em have} to have a @mk/build.mk@ file at all; if you don't,
you'll get all the default settings from @mk/config.mk.in@.
+You can also use @build.mk@ to override anything that @configure@ got
+wrong. One place where this happens often is with the definition of
+@FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path
+to the top of your source tree, but if your system uses an automounter
+then the correct directory is hard to find automatically. If you find
+that @configure@ has got it wrong, just put the correct definition in
+@build.mk@.
\subsection{The story so far}
\item Get your source tree from somewhere (CVS repository or
source distribution). Say you call the root directory
@myfptools@ (it does not have to be called @fptools@).
+Make sure that you have the essential files (see Section~\ref{source-tree}).
\item Use @lndir@ or @mkshadowdir@ to create a build tree.
\begin{verbatim}
\item Prepare for system configuration:
\begin{verbatim}
autoconf
- autoheader
\end{verbatim}
(You can skip this step if you are starting from a source distribution,
and you already have @configure@ and @mk/config.h.in@.)
for the real work. Notably, it does @gmake depend@ in all directories
that contain programs. But @boot@ does more. For example, you can't
do @gmake depend@ in a directory of C program until you have converted
-the literate @.lh@ header files into standard @.h@ header files. Similarly, you convert a literate file to illiterate
-form until you have built the @literate@ tools. @boot@ takes care of these
+the literate @.lh@ header files into standard @.h@ header files.
+Similarly, you convert a literate file to illiterate form until you
+have built the @literate@ tools. @boot@ takes care of these
inter-directory dependencies.
-You should say @gmake boot@ right after configuring your build tree.
+You should say @gmake boot@ right after configuring your build tree,
+but note that this is a one-off, i.e., there's no need to re-do
+@gmake boot@ if you should re-configure your build tree at a later
+stage (no harm caused if you do though).
\item[@all@:] makes all the final target(s) for this Makefile.
Depending on which directory you are in a ``final target''
because no binaries have been provided, or because the machine
is not ``fully supported.''
-THIS SECTION HASN'T BEEN UPDATED YET. Please let us know if you want to use this
-route. Unless someone does, this section may never get written, and the
-.hc files distribution may not get built!
+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've haven't made them available or you
+can't find them, please ask.
+
+Assuming you've got them, unpack them on top of a fresh source tree.
+Then follow the `normal' instructions in
+\sectionref{building-from-source} for setting up a build tree and
+configuring it. The only extra thing to remember when booting from
+\tr{.hc} files is to add the following line to the \tr{build.mk}
+file:
+
+\begin{verbatim}
+GhcWithHscBuiltViaC=YES
+\end{verbatim}
+
+and proceed with doing a \tr{make boot} followed by a \tr{make all}.
+
+That's the mechanics of the boot process, but, of course, if you're
+trying to boot on a platform that is not supported and significantly
+`different' from any of the supported ones, this is only the start
+of the adventure...(ToDo: porting tips - stuff to look out for, etc.)
%************************************************************************
The best way around it is to say
\begin{verbatim}
- TMPDIR=<dir>
+export TMPDIR=<dir>
\end{verbatim}
in your @build.mk@ file.
Then GHC and the other @fptools@ programs will use the appropriate directory
\item
You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
\begin{verbatim}
-% cd $(libdir)/ghc-2.01/sparc-sun-sunos4
+% 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
you can do \tr{make -n whatever.dvi} to see the intended commands,
then try to muddle through, doing them by hand.
-\end{enumerate}
-
-
-
-% ====================================================================
-Here follow pitfalls that apply to pre-2.02 releases. They should not
-happen any more If they do crop up with 2.02 or later, please let us
-know.
-
-\begin{enumerate}
-%------------------------------------------------------------------------
-\item
-When configuring the support code (mkworld, glafp-utils, etc.), you
-will see mention of \tr{NO_SPECIFIC_PROJECT} and
-\tr{NO_SPECIFIC_VERSION}. This is cool.
-
-
%------------------------------------------------------------------------
\item
-Sooner or later in your ``make-worlding'' life you will do and see
-something like:
+GHC's sources go through \tr{cpp}
+before being compiled, and \tr{cpp} varies a bit from one Unix to another.
+One particular gotcha is macro calls like this:
\begin{verbatim}
-% make Makefile
- rm -f Makefile.bak; mv Makefile Makefile.bak
-../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=...
-../.././mkworld/jrestoredeps
-==== The new Makefile is for: ====
-make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen
-Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard
-*** Error code 1
-make: Fatal error: Command failed for target `Makefile'
+ SLIT("Hello, world")
\end{verbatim}
-
-Don't panic! It should restore your previous \tr{Makefile}, and
-leave the junk one in \tr{Makefile.bad}. Snoop around at your leisure.
-
-% ------------------------------------------------------------------------
-\item
-If you do corrupt a \tr{Makefile} totally, or you need to glue a new
-directory into the directory structure (in \tr{newdir}---which must
-have a \tr{Jmakefile}, even if empty), here's a neat trick:
+Some \tr{cpp}s treat the comma inside the string as separating two macro arguments,
+so you get
\begin{verbatim}
-#
-# move to the directory just above the one where you want a Makefile...
-cd ..
-#
-# make Makefiles, but lie about the directories below...
-make Makefiles SUBDIRS=newdir
+ :731: macro `SLIT' used with too many (2) args
\end{verbatim}
+Alas, \tr{cpp} doesn't tell you the offending file!
-This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and
-it will be properly wired into the general make-world structure.
-
-% ------------------------------------------------------------------------
-\item
-Don't configure/build/install using a variety of machines. A
-mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to
-build GHC (\tr{make all}) on a Sun3.
-
-%------------------------------------------------------------------------
-%\item
-%If you build an ``unregisterised'' build, you will get bazillions of
-%warnings about `ANSI C forbids braced-groups within expressions'.
-%Especially in \tr{ghc/lib}. These are OK.
-
+Workaround: don't put wierd things in string args to \tr{cpp} macros.
\end{enumerate}
-
\begin{onlystandalone}
\printindex
\end{document}
projects / ghc-hetmet.git / blobdiff