% Building and installing the Glasgow Functional Programming Tools Suite
%
-% Version 2.05
+% Version 3.00
% July 1997
\documentstyle[11pt,literate]{article}
\begin{document}
\title{Building and installing the Glasgow Functional Programming Tools Suite\\
-Version~2.05}
+Version~3.00}
\author{The GHC Team\\
Department of Computing Science\\
University of Glasgow\\
as suggested:
\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
-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.}
+
+\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 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. Section~\ref{installing-bin-distrib} describes
+how to do this.
A binary distribution may not work for you for two reasons. First, we
may not have built the suite for the particular architecture/OS
Source-only distributions are either bugfix releases or snapshots of
current state of development. The release has undergone some testing.
-
-GHC~2.05 is a source-only release, and it can be compiled up using
-either GHC~2.02 (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.04 is catching up.
+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
\item[The CVS repository.]
-We make source distributions at the same time as binary distributions;
-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.
+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.
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
at our end; and we are a bit nervous about being submerged in bug reports
about our current working copy (which is, by definition, in flux). So
we are a bit cautious about offering CVS access. Feel free to ask though!
-\end{description}
+\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
\item
Use an appropriate machine, compilers, and things.
-SPARC boxes and DEC Alphas running OSF/1 are fully supported.
-Linux, MIPS, AIX, Win32 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.
Section~\ref{sect_std-utils} elaborates.
-\item
-If you have any problem when building or installing the Glasgow tools,
-please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If
-you feel there is still some shortcoming in our procedure or
+\item If you have any problem when building or installing the Glasgow
+tools, please check the ``known pitfalls''
+(\sectionref{build-pitfalls}). Also check the ``known bugs'' web page
+for GHC:
+
+\begin{center}
+@http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html@
+\end{center}
+
+If you feel there is still some shortcoming in our procedure or
instructions, please report it.
For GHC, please see the bug-reporting section of the User's guide
(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 @glasgow-haskell-bugs@@dcs.gla.ac.uk@.
\end{enumerate}
%************************************************************************
%* *
-\section[port-info]{What machines the Glasgow tools, version~2.05, run on}
+\section[port-info]{What machines the Glasgow tools run on}
\index{ports, GHC}
\index{GHC ports}
\index{supported platforms}
The main question is whether or not the Haskell compiler (GHC) runs on
your platform.
-A ``platform'' is a
-architecture/manufacturer/operating-system combination,
-such as @sparc-sun-solaris2.5.1@. Other common ones are
+A ``platform'' is a architecture/manufacturer/operating-system
+combination, such as @sparc-sun-solaris2@. Other common ones are
@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
-@i386-unknown-solaris2@, @i386-unknown-freebsd@, @i386-unknown-cygwin32@,
-@m68k-sun-sunos4@, @mips-sgi-irix5@, @sparc-sun-sunos4@,
-@sparc-sun-solaris2@, @powerpc-ibm-aix@.
+@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.
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.05. We
-identify platforms by their ``canonical'' CPU/Manufacturer/OS triple.
+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.05 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.05 works registerised. Supports same set of
-bundles as the above.
+NetBSD/OpenBSD using FreeBSD emulation):]
+\index{i386-*-freebsd:registerised port}
+GHC works registerised. Supports same set of bundles as the above.
\index{i386-*-freebsd: profiling---yes}
\index{i386-*-freebsd: concurrent---yes}
%-------------------------------------------------------------------
\item[\tr{mips-sgi-irix5}:]
\index{mips-sgi-irix5: registerised port}
-GHC~2.05 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!
\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~2.05 works registerised
+\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
%-------------------------------------------------------------------
\item[\tr{powerpc-ibm-aix}:]
\index{powerpc-ibm-aix: registerised port}
-GHC~2.05 works registerised (no native-code generator..yet).
+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).
%-------------------------------------------------------------------
\item[\tr{m68k-sun-sunos4} (Sun3):]
\index{m68k-sun-sunos4: registerised port}
-GHC~2.05 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:
\item[@configure@] the configuration script (\sectionref{sect_install}).
\item[@README@] Contains this file summary.
\item[@INSTALL@] Contains this description of how to install the bundle.
-\item[@ANNOUNCE-<bundle>@] The announcement message for the bundle.
-\item[@NEWS-<bundle>@] release notes for the bundle -- a longer version of @ANNOUNCE@.
-\item[@bin/<platform>/@] contains platform-specific executable files to be invoked
+\item[@ANNOUNCE@] The announcement message for the bundle.
+\item[@NEWS@] release notes for the bundle -- a longer version of
+@ANNOUNCE@. For GHC, the release notes are contained in the User
+Guide and this file isn't present.
+\item[@bin/<platform>@] contains platform-specific executable files to be invoked
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.
\subsection[sect_install]{Installing}
-OK, so let's assume that you have unpacked your chosen bundles into
-a scratch directory @fptools@. What next? Well, you will at least need
-to run the @configure@ script by changing your directory to @fptools@.
-That should convert @Makefile.in@ to @Makefile@.
+OK, so let's assume that you have unpacked your chosen bundles into a
+scratch directory @fptools@. What next? Well, you will at least need
+to run the @configure@ script by changing your directory to @fptools@
+and typing @./configure@. 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 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.
+tools up for this (where @make@ is GNU make - you might have to type
+@gmake@ to get it). 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 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.05-<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.05/ghc/driver/ghc ~/bin/alpha/ghc
+% ln -s /local/src/ghc-x.xx/ghc/driver/ghc ~/bin/alpha/ghc
% rehash
\end{verbatim}
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}
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 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@.)
to happen that you can read and understand any wierd special cases yourself.
\begin{description}
-\item{@HS_PROG@.} If @HS_PROG@ is defined, you get rules with the
+\item[@HS_PROG@.] If @HS_PROG@ is defined, you get rules with the
following targets:
\begin{description}
\item[@HS_PROG@] itself. This rule links @$(OBJS)@ with the Haskell
\item
You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
\begin{verbatim}
-% cd $(libdir)/ghc-2.05/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
Workaround: don't put wierd things in string args to \tr{cpp} macros.
\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:
-%\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'
-%\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:
-%\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
-%\end{verbatim}
-
-%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.
-
-\end{enumerate}
-
-
\begin{onlystandalone}
\printindex
\end{document}
projects / ghc-hetmet.git / blobdiff