X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=cc687195c0e9282cdcacee23d44204a5000d19a6;hb=968763d90f3a833923bb5f07c998a079a3f5f5bc;hp=80398f303d9c34d3b5e067c173f0fef2be335124;hpb=cccb6444f80ceb5adb36dbba2f1844b333a0e3f3;p=ghc-hetmet.git
diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index 80398f3..cc68719 100644
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -58,7 +58,7 @@
the parser specifications. If you don't want to alter the
parser then this saves you having to find and install
happy. You will still need a working
- version of GHC (preferably version 4.08+) on your machine in
+ version of GHC (version 5.x or later) on your machine in
order to compile (most of) the sources, however.
@@ -137,6 +137,12 @@
Set your $CVSROOT environment variable to
:pserver:anoncvs@glass.cse.ogi.edu:/cvs
+ If you set $CVSROOT in a shell script, be sure not to
+ have any trailing spaces on that line, otherwise CVS will respond with
+ a perplexing message like
+
+ /cvs : no such repository
+ Run the command
@@ -240,24 +246,10 @@
- [Windows users.] The programs ssh-keygen1, ssh1, and cvs,
- seem to lock up bash entirely if they try to get user input (e.g. if
- they ask for a password). To solve this, start up cmd.exe
- and run it as follows:
-
- c:\tmp> set CYGWIN32=tty
- c:\tmp> c:/user/local/bin/ssh-keygen1
-
+ Windows users: see the notes in about ssh wrinkles!
+
+
- [Windows users.] To protect your
- .ssh from access by anyone else,
- right-click your .ssh 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!
@@ -437,14 +429,19 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument
the fpconfig bit.
$ cd directory
- $ cvs checkout ghc hslibs
+ $ cvs checkout ghc hslibs libraries
The second command here checks out the relevant
modules you want to work on. For a GHC build, for instance,
- you need at least the ghc and
- hslibs modules (for a full list of the
- projects available, see ).
+ you need at least the ghc,
+ hslibs and libraries
+ modules (for a full list of the projects available, see
+ ).
+
+ Remember that if you do not have
+ happy and/or Alex
+ installed, you need to check them out as well.
@@ -480,7 +477,14 @@ $ cvs diff
you the results.
-
+
+ If you changed something in the
+ fptools/libraries subdirectories, also run
+ make html to check if the documentation can
+ be generated successfully, too.
+
+
+ Before checking in a change, you need to update your
source tree:
@@ -563,17 +567,25 @@ $ cvs commit -F commit-messagedirectory
major cause of headaches.
So, to avoid a lot of hassle, follow this recipe for
- updating your tree:
+ updating your tree:
$ cd fptools
-$ cvs update -Pd 2>&1 | tee log
+$ cvs update -P 2>&1 | tee log
Look at the log file, and fix any conflicts (denoted by a
- C in the first column). If you're using multiple
- build trees, then for every build tree you have pointing at this
- source tree, you need to update the links in case any new files
- have appeared:
+ C in the first column). New directories may have
+ appeared in the repository; CVS doesn't check these out by
+ default, so to get new directories you have to explicitly do
+
+$ cvs update -d
+ in each project subdirectory. Don't do this at the top level,
+ because then all the projects will be
+ checked out.
+
+ If you're using multiple build trees, then for every build
+ tree you have pointing at this source tree, you need to update
+ the links in case any new files have appeared:
$ cd build-tree
@@ -714,6 +726,17 @@ $ cvs checkout nofib/spectral
+ alex
+ alex
+ project
+
+ The Alex lexical
+ analyser generator for Haskell.
+
+
+
+ ghcghcproject
@@ -735,11 +758,11 @@ $ cvs checkout nofib/spectral
- green-card
- green-cardproject
+ greencard
+ greencardprojectThe Green Card
+ url="http://www.haskell.org/greencard/">GreenCard
system for generating Haskell foreign function
interfaces.
@@ -983,12 +1006,21 @@ $ cvs checkout nofib/spectral
sparc-sun-solaris2sparc-sun-solaris2
- Fully supported (at least for Solaris 2.7),
+ Fully supported (at least for Solaris 2.7 and 2.6),
including native-code generator.
+ sparc-unknown-openbsd
+ sparc-unknown-openbsd
+
+ Supported, including native-code generator. The
+ same should also be true of NetBSD
+
+
+
+ hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)hppa1.1-hp-hpux
@@ -1063,6 +1095,15 @@ $ cvs checkout nofib/spectral
ia64-unknown-linuxia64-unknown-linux
+ Supported, except there is no native code
+ generator.
+
+
+
+
+ x86_64-unknown-linux
+ x86_64-unknown-linux
+ GHC currently works unregisterised. A registerised
port is in progress.
@@ -1081,6 +1122,14 @@ $ cvs checkout nofib/spectral
+ mips64-sgi-irix6
+ mips-sgi-irix6
+
+ GHC currently works unregisterised.
+
+
+
+ powerpc-ibm-aixpowerpc-ibm-aix
@@ -1095,8 +1144,8 @@ $ cvs checkout nofib/spectral
powerpc-apple-darwinpowerpc-apple-darwin
- Supported registerised. No native code
- generator.
+ Supported registerised. Native code generator is
+ almost working.
@@ -1141,6 +1190,23 @@ $ cvs checkout nofib/spectral
+ GHC
+ pre-supposed: GHC
+ GHC, pre-supposed
+
+ GHC is required to build many of the tools, including
+ GHC itself. If you need to port GHC to your platform
+ because there isn't a binary distribution of GHC available,
+ then see .
+
+ Which version of GHC you need will depend on the
+ packages you intend to build. GHC itself will normally
+ build using one of several older versions of itself - check
+ the announcement or release notes for details.
+
+
+
+ Perlpre-supposed: PerlPerl, pre-supposed
@@ -1177,9 +1243,12 @@ $ cvs checkout nofib/spectral
egcs) have varying degrees of stability
depending on the platform.
+ GCC 3.2 is currently known to have problems building
+ GHC on Sparc, but is stable on x86.
+
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
+ it and get things improved. (Exception: on x86
boxes—you may need to fiddle with GHC's
option; see the User's
Guide)
@@ -1208,7 +1277,7 @@ $ cvs checkout nofib/spectral
(fptools/happy). It can be built from
source, but bear in mind that you'll need GHC installed in
order to build it. To avoid the chicken/egg problem,
- install a binary distribtion of either Happy or GHC to get
+ install a binary distribution of either Happy or GHC to get
started. Happy distributions are available from Happy's Web
Page.
@@ -1216,6 +1285,19 @@ $ cvs checkout nofib/spectral
+ Alex
+ Alex
+
+ Alex is a lexical-analyser generator for Haskell,
+ which GHC uses to generate its lexer. Like Happy, Alex is
+ written in Haskell and is a project in the CVS repository.
+ Alex distributions are available from Alex's Web
+ Page.
+
+
+
+ Autoconfpre-supposed: AutoconfAutoconf, pre-supposed
@@ -1224,8 +1306,12 @@ $ cvs checkout nofib/spectral
CVS sources, it is not needed if you
just intend to build a standard source distribution.
+ Version 2.52 or later of autoconf is required.
+ NB. vesrion 2.13 will no longer work, as of GHC version
+ 6.1.
+
Autoconf builds the configure
- script from configure.in and
+ script from configure.ac and
aclocal.m4. If you modify either of
these files, you'll need autoconf to
rebuild configure.
@@ -1265,7 +1351,7 @@ $ cvs checkout nofib/spectral
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
+ plan to run Parallel Haskell. Concurrent 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
@@ -1295,46 +1381,6 @@ $ cvs checkout nofib/spectral
-
- Tools for building the Documentation
-
- The following additional tools are required if you want to
- format the documentation that comes with the
- fptools projects:
-
-
-
- DocBook
- pre-supposed: DocBook
- DocBook, pre-supposed
-
- All our documentation is written in SGML, using the
- DocBook DTD. Instructions on installing and configuring
- the DocBook tools are in the installation guide (in the
- GHC user guide).
-
-
-
-
- TeX
- pre-supposed: TeX
- TeX, pre-supposed
-
- A decent TeX distribution is required if you want to
- produce printable documentation. We recomment teTeX,
- which includes just about everything you need.
-
-
-
-
- In order to actually build any documentation, you need to
- set SGMLDocWays in your
- build.mk. Valid values to add to this list
- are: dvi, ps,
- pdf, html, and
- rtf.
-
-
Other useful tools
@@ -1352,6 +1398,10 @@ $ cvs checkout nofib/spectral
+
+ More tools are required if you want to format the documentation
+ that comes with GHC and other fptools projects. See .
@@ -1377,6 +1427,26 @@ $ cvs checkout nofib/spectral
software, and lay hands on them gently when they don't
work.
+
+ Quick Start
+
+ If you are starting from a source distribution, and just
+ want a completely standard build, then the following should
+ work:
+
+$ ./configure
+$ make
+$ make install
+
+
+ For GHC, this will do a 2-stage bootstrap build of the
+ compiler, with profiling libraries, and install the
+ results.
+
+ If you want to do anything at all non-standard, or you
+ want to do some development, read on...
+
+
Your source tree
@@ -1398,7 +1468,7 @@ $ cvs checkout nofib/spectral
- configure.in,
+ configure.ac,
config.sub,
config.guess: these files support the
configuration process.
@@ -1421,7 +1491,7 @@ $ cvs checkout nofib/spectral
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
+ configure.ac, and the project(s) you want
(happy/ in this case). You cannot get by
with just the happy/ directory.
@@ -1530,34 +1600,31 @@ $ cvs checkout nofib/spectral
Step 1: get ready for configuration.
+ NOTE: if you're starting from a source distribution,
+ rather than CVS sources, you can skip this step.
+
Change directory to
$(FPTOOLS_TOP) and
issue the command
autoconfautoconf
(with no arguments). This GNU program converts
- $(FPTOOLS_TOP)/configure.in
+ $(FPTOOLS_TOP)/configure.ac
to a shell script called
$(FPTOOLS_TOP)/configure.
Some projects, including GHC, have their own
configure script. If there's an
- $(FPTOOLS_TOP)/<project>/configure.in,
+ $(FPTOOLS_TOP)/<project>/configure.ac,
then you need to run autoconf in that
directory too.Both these steps are completely
platform-independent; they just mean that the
- human-written file (configure.in) can
+ human-written file (configure.ac) can
be short, although the resulting shell script,
configure, and
mk/config.h.in, are long.
-
- 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.
@@ -1575,7 +1642,7 @@ $ cvs checkout nofib/spectral
round your computer working out what architecture it has,
what operating system, whether it has the
vfork system call, where
- yacc is kept, whether
+ tar is kept, whether
gcc is available, where various obscure
#include files are, whether it's a
leap year, and what the systems manager had for lunch. It
@@ -1712,6 +1779,9 @@ $ cvs checkout nofib/spectral
includes build.mk after
config.mk.)
+ For your convenience, there's a file called build.mk.sample
+ that can serve as a starting point for your build.mk.
+
For example, config.mk.in contains
the definition:
@@ -1752,17 +1822,17 @@ GhcHcOpts=-DDEBUG -Rghc-timing
For example, there's a line that says:
-YACC = @YaccCmd@
+TAR = @TarCmd@
- This defines the Make variables YACC
- to the pathname for a yacc that
+ This defines the Make variables TAR
+ to the pathname for a tar that
configure finds somewhere. If you have your
- own pet yacc you want to use instead, that's
+ own pet tar you want to use instead, that's
fine. Just add this line to mk/build.mk:
-YACC = myyacc
+TAR = mytar
You do not have to have a
@@ -1900,7 +1970,92 @@ $ emacs mk/build.mk
the top of your fptools tree and type
gmake. This will prepare the tree and build
the various projects in the correct order.
+
+
+
+ Bootstrapping GHC
+
+ GHC requires a 2-stage bootstrap in order to provide
+ full functionality, including GHCi. By a 2-stage bootstrap, we
+ mean that the compiler is built once using the installed GHC,
+ and then again using the compiler built in the first stage. You
+ can also build a stage 3 compiler, but this normally isn't
+ necessary except to verify that the stage 2 compiler is working
+ properly.
+
+ Note that when doing a bootstrap, the stage 1 compiler
+ must be built, followed by the runtime system and libraries, and
+ then the stage 2 compiler. The correct ordering is implemented
+ by the top-level fptools Makefile, so if
+ you want everything to work automatically it's best to start
+ make from the top of the tree. When building
+ GHC, the top-level fptools Makefile is set
+ up to do a 2-stage bootstrap by default (when you say
+ make). Some other targets it supports
+ are:
+
+
+
+ stage1
+
+ Build everything as normal, including the stage 1
+ compiler.
+
+
+
+
+ stage2
+
+ Build the stage 2 compiler only.
+
+
+
+
+ stage3
+
+ Build the stage 3 compiler only.
+
+
+
+
+ bootstrapbootstrap2
+
+ Build stage 1 followed by stage 2.
+
+
+
+ bootstrap3
+
+ Build stages 1, 2 and 3.
+
+
+
+
+ install
+
+ Install everything, including the compiler built in
+ stage 2. To override the stage, say make install
+ stage=n where
+ n is the stage to install.
+
+
+
+
+ The top-level Makefile also arranges
+ to do the appropriate make boot steps (see
+ below) before actually building anything.
+
+ The stage1, stage2
+ and stage3 targets also work in the
+ ghc/compiler directory, but don't forget that
+ each stage requires its own make boot step:
+ for example, you must do
+
+ $ make boot stage=2
+
+ before make stage2 in
+ ghc/compiler.
@@ -2113,13 +2268,14 @@ Foo.o : Baz.hi
Do NOT use
ghc/compiler/ghc, or
- ghc/compiler/ghc-5.xx, as these are the
+ ghc/compiler/ghc-6.xx, as these are the
scripts intended for installation, and contain hard-wired paths
to the installed libraries, rather than the libraries in the
build tree.Happy can similarly be run from the build tree, using
- happy/src/happy-inplace.
+ happy/src/happy-inplace, and similarly for
+ Alex and Haddock.
@@ -3201,6 +3357,266 @@ $ make way=p
+
+ Building the documentation
+
+
+ Tools for building the Documentation
+
+ The following additional tools are required if you want to
+ format the documentation that comes with the
+ fptools projects:
+
+
+
+ DocBook
+ pre-supposed: DocBook
+ DocBook, pre-supposed
+
+ Much of our documentation is written in SGML, using
+ the DocBook DTD. Instructions on installing and
+ configuring the DocBook tools are below.
+
+
+
+
+ TeX
+ pre-supposed: TeX
+ TeX, pre-supposed
+
+ A decent TeX distribution is required if you want to
+ produce printable documentation. We recomment teTeX,
+ which includes just about everything you need.
+
+
+
+
+ Haddock
+ Haddock
+
+
+ Haddock is a Haskell documentation tool that we use
+ for automatically generating documentation from the
+ library source code. It is an fptools
+ project in itself. To build documentation for the
+ libraries (fptools/libraries) you
+ should check out and build Haddock in
+ fptools/haddock. Haddock requires GHC
+ to build.
+
+
+
+
+
+
+ Installing the DocBook tools
+
+
+ Installing the DocBook tools on Linux
+
+ If you're on a recent RedHat system (7.0+), you probably
+ have working DocBook tools already installed. The configure
+ script should detect your setup and you're away.
+
+ If you don't have DocBook tools installed, and you are
+ using a system that can handle RedHat RPM packages, you can
+ probably use the Cygnus
+ DocBook tools, 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). Note that most of these
+ RPMs are architecture neutral, so are likely to be found in a
+ noarch directory. The SuSE RPMs also
+ work; the RedHat ones don't in RedHat 6.2
+ (7.0 and later should be OK), but they are easy to fix: just
+ make a symlink from
+ /usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl
+ to /usr/lib/sgml/lib/dblib.dsl.
+
+
+
+ Installing DocBook on FreeBSD
+
+ On FreeBSD systems, the easiest way to get DocBook up
+ and running is to install it from the ports tree or a
+ pre-compiled package (packages are available from your local
+ FreeBSD mirror site).
+
+ To use the ports tree, do this:
+
+ $ cd /usr/ports/textproc/docproj
+ $ make install
+
+ This installs the FreeBSD documentation project tools, which
+ includes everything needed to format the GHC
+ documentation.
+
+
+
+ Installing from binaries on Windows
+
+ It's a good idea to use Norman Walsh's installation
+ notes as a guide. You should get version 3.1 of
+ DocBook, and note that his file test.sgm
+ won't work, as it needs version 3.0. You should unpack Jade
+ into \Jade, along with the entities,
+ DocBook into \docbook, and the DocBook
+ stylesheets into \docbook\stylesheets (so
+ they actually end up in
+ \docbook\stylesheets\docbook).
+
+
+
+
+ Installing the DocBook tools from source
+
+
+ Jade
+
+ Install OpenJade
+ (Windows binaries are available as well as sources). If you
+ want DVI, PS, or PDF then install JadeTeX from the
+ dsssl subdirectory. (If you get the
+ error:
+
+
+! LaTeX Error: Unknown option implicit=false' for package hyperref'.
+
+
+ your version of hyperref is out of date;
+ download it from CTAN
+ (macros/latex/contrib/supported/hyperref),
+ and make it, ensuring that you have first removed or renamed
+ your old copy. If you start getting file not found errors
+ when making the test for hyperref, you
+ can abort at that point and proceed straight to
+ make install, or enter them as
+ ../filename.)
+
+ Make links from virtex to
+ jadetex and
+ pdfvirtex to
+ pdfjadetex (otherwise DVI, PostScript
+ and PDF output will not work). Copy
+ dsssl/*.{dtd,dsl} and
+ catalog to
+ /usr/[local/]lib/sgml.
+
+
+
+ DocBook and the DocBook stylesheets
+
+ Get a Zip of DocBook
+ and install the contents in
+ /usr/[local/]/lib/sgml.
+
+ Get the DocBook
+ stylesheets and install in
+ /usr/[local/]lib/sgml/stylesheets
+ (thereby creating a subdirectory docbook). For indexing,
+ copy or link collateindex.pl from the
+ DocBook stylesheets archive in bin into
+ a directory on your PATH.
+
+ Download the ISO
+ entities into
+ /usr/[local/]lib/sgml.
+
+
+
+
+
+ Configuring the DocBook tools
+
+ Once the DocBook tools are installed, the configure script
+ will detect them and set up the build system accordingly. If you
+ have a system that isn't supported, let us know, and we'll try
+ to help.
+
+
+
+ Remaining problems
+
+ If you install from source, you'll get a pile of warnings
+ of the form
+
+DTDDECL catalog entries are not supported
+
+ every time you build anything. These can safely be ignored, but
+ if you find them tedious you can get rid of them by removing all
+ the DTDDECL entries from
+ docbook.cat.
+
+
+
+ Building the documentation
+
+ To build documentation in a certain format, you can
+ say, for example,
+
+
+$ make html
+
+
+ to build HTML documentation below the current directory.
+ The available formats are: dvi,
+ ps, pdf,
+ html, and rtf. Note that
+ not all documentation can be built in all of these formats: HTML
+ documentation is generally supported everywhere, and DocBook
+ documentation might support the other formats (depending on what
+ other tools you have installed).
+
+ All of these targets are recursive; that is, saying
+ make html will make HTML docs for all the
+ documents recursively below the current directory.
+
+ Because there are many different formats that the DocBook
+ documentation can be generated in, you have to select which ones
+ you want by setting the SGMLDocWays variable
+ to a list of them. For example, in
+ build.mk you might have a line:
+
+
+SGMLDocWays = html ps
+
+
+ This will cause the documentation to be built in the requested
+ formats as part of the main build (the default is not to build
+ any documentation at all).
+
+
+
+ Installing the documentation
+
+ To install the documentation, use:
+
+
+$ make install-docs
+
+
+ This will install the documentation into
+ $(datadir) (which defaults to
+ $(prefix)/share). The exception is HTML
+ documentation, which goes into
+ $(datadir)/html, to keep things tidy.
+
+ Note that unless you set $(SGMLDocWays)
+ to a list of formats, the install-docs target
+ won't do anything for SGML documentation.
+
+
+
+
+
Porting GHC
@@ -3239,17 +3655,16 @@ $ make way=p
target machine, and compiling them using gcc to get a working
GHC.
- NOTE: GHC version 5.xx is significantly harder
- to bootstrap from C than previous versions. We recommend
- starting from version 4.08.2 if you need to bootstrap in this
- way.
+ NOTE: GHC versions 5.xx were hard to bootstrap
+ from C. We recommend using GHC 6.0.1 or
+ later.
- HC files are architecture-dependent (but not
- OS-dependent), so you have to get a set that were generated on
- similar hardware. There may be some supplied on the GHC
- download page, otherwise you'll have to compile some up
- yourself, or start from unregisterised HC
- files - see .
+ HC files are platform-dependent, so you have to get a set
+ that were generated on similar hardware. There may be some
+ supplied on the GHC download page, otherwise you'll have to
+ compile some up yourself, or start from
+ unregisterised HC files - see .The following steps should result in a working GHC build
with full libraries:
@@ -3263,8 +3678,8 @@ $ make way=p
corresponding Haskell source (.hs or
.lhs) in the compiler subdirectory
ghc/compiler and in the libraries
- (ghc/lib, and subdirectories of
- hslibs).
+ (subdirectories of hslibs and
+ libraries).
@@ -3333,65 +3748,239 @@ foo% make install
since unregisterised compilation is usually just a step on the
way to a full registerised port, we don't mind too much.
-
- Building an unregisterised port
+ Notes on GHC portability in general: we've tried to stick
+ to writing portable code in most parts of the system, so it
+ should compile on any POSIXish system with gcc, but in our
+ experience most systems differ from the standards in one way or
+ another. Deal with any problems as they arise - if you get
+ stuck, ask the experts on
+ glasgow-haskell-users@haskell.org.
- The first step is to get some unregisterised HC files.
- Either (a) download them from the GHC site (if there are
- some available for the right version of GHC), or
- (b) build them yourself on any machine with a working
- GHC. If at all possible this should be a machine with the
- same word size as the target.
-
- There is a script available which should automate the
- process of doing the 2-stage bootstrap necessary to get the
- unregisterised HC files - it's available in fptools/distrib/cross-port
- in CVS.
-
- Now take these unregisterised HC files to the target
- platform and bootstrap a compiler from them as per the
- instructions in . In
- build.mk, you need to tell the build
- system that the compiler you're building is
- (a) unregisterised itself, and (b) builds
- unregisterised binaries. This varies depending on the GHC
- version you're bootstraping:
+ Lots of useful information about the innards of GHC is
+ available in the GHC
+ Commentary, which might be helpful if you run into some
+ code which needs tweaking for your system.
-
-# build.mk for GHC 4.08.x
-GhcWithRegisterised=NO
-
+
+ Cross-compiling to produce an unregisterised GHC
+
+ In this section, we explain how to bootstrap GHC on a
+ new platform, using unregisterised intermediate C files. We
+ haven't put a great deal of effort into automating this
+ process, for two reasons: it is done very rarely, and the
+ process usually requires human intervention to cope with minor
+ porting issues anyway.
+
+ The following step-by-step instructions should result in
+ a fully working, albeit unregisterised, GHC. Firstly, you
+ need a machine that already has a working GHC (we'll call this
+ the host machine), in order to
+ cross-compile the intermediate C files that we will use to
+ bootstrap the compiler on the target
+ machine.
+
+
+
+ On the target machine:
+
+
+
+ Unpack a source tree (preferably a released
+ version). We will call the path to the root of this
+ tree T.
+
+
+
+
+$ cd T
+$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
+
+
+ You might need to update
+ configure.in to recognise the new
+ architecture, and re-generate
+ configure with
+ autoreconf.
+
+
+
+
+$ cd T/ghc/includes
+$ make config.h
+
+
+
+
+
+
+ On the host machine:
+
+
+
+ Unpack a source tree (same released version). Call
+ this directory H.
+
+
+
+
+$ cd H
+$ ./configure
+
+
+
+
+ Create
+ H/mk/build.mk,
+ with the following contents:
-# build.mk for GHC 5.xx
-GhcUnregisterised=YES
+GhcUnregisterised = YES
+GhcLibHcOpts = -O -H32m -keep-hc-files
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
+GhcStage1HcOpts = -O -H32m -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files
+
- Version 5.xx only: use the option
- instead of
- when running
- ./configure.
-
- The build may not go through cleanly. We've tried to
- stick to writing portable code in most parts of the compiler,
- so it should compile on any POSIXish system with gcc, but in
- our experience most systems differ from the standards in one
- way or another. Deal with any problems as they arise - if you
- get stuck, ask the experts on
- glasgow-haskell-users@haskell.org.
-
- Once you have the unregisterised compiler up and
- running, you can use it to start a registerised port. The
- following sections describe the various parts of the system
- that will need architecture-specific tweaks in order to get a
- registerised build going.
-
- Lots of useful information about the innards of GHC is
- available in the GHC
- Commentary, which might be helpful if you run into
- some code which needs tweaking for your system.
+
+ Edit
+ H/mk/config.mk:
+
+
+ change TARGETPLATFORM
+ appropriately, and set the variables involving
+ TARGET to the correct values for
+ the target platform. This step is necessary because
+ currently configure doesn't cope
+ with specifying different values for the
+ --host and
+ --target flags.
+
+
+ copy LeadingUnderscore
+ setting from target.
+
+
+
+
+
+ Copy
+ T/ghc/includes/config.h
+ to
+ H/ghc/includes.
+ Note that we are building on the host machine, using the
+ target machine's config.h file. This
+ is so that the intermediate C files generated here will
+ be suitable for compiling on the target system.
+
+
+
+
+ Touch config.h, just to make
+ sure it doesn't get replaced during the build:
+
+$ touch H/ghc/includes/config.h
+
+
+
+ Now build the compiler:
+
+$ cd H/glafp-utils && make boot && make
+$ cd H/ghc && make boot && make
+
+ Don't worry if the build falls over in the RTS, we
+ don't need the RTS yet.
+
+
+
+
+$ cd H/libraries
+$& make boot && make
+
+
+
+
+
+$ cd H/ghc
+$ make boot stage=2 && make stage=2
+
+
+
+
+
+$ cd H/ghc/utils
+$ make clean
+$ make -k HC=H/ghc/compiler/stage1/ghc-inplace \
+ EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+
+
+
+
+
+$ cd H
+$ make hc-file-bundle Project=Ghc
+
+
+
+
+ copy
+ H/*-hc.tar.gz
+ to T/...
+
+
+
+
+
+ On the target machine:
+
+ At this stage we simply need to bootstrap a compiler
+ from the intermediate C files we generated above. The
+ process of bootstrapping from C files is automated by the
+ script in distrib/hc-build, and is
+ described in .
+
+
+$ ./distrib/hc-build --enable-hc-boot-unregisterised
+
+
+ However, since this is a bootstrap on a new machine,
+ the automated process might not run to completion the
+ first time. For that reason, you might want to treat the
+ hc-build script as a list of
+ instructions to follow, rather than as a fully automated
+ script. This way you'll be able to restart the process
+ part-way through if you need to fix anything on the
+ way.
+
+ Don't bother with running
+ make install in the newly
+ bootstrapped tree; just use the compiler in that tree to
+ build a fresh compiler from scratch, this time without
+ booting from C files. Before doing this, you might want
+ to check that the bootstrapped compiler is generating
+ working binaries:
+
+
+$ cat >hello.hs
+main = putStrLn "Hello World!\n"
+^D
+$ T/ghc/compiler/ghc-inplace hello.hs -o hello
+$ ./hello
+Hello World!
+
+
+ Once you have the unregisterised compiler up and
+ running, you can use it to start a registerised port. The
+ following sections describe the various parts of the
+ system that will need architecture-specific tweaks in
+ order to get a registerised build going.
+
+
+
@@ -3518,10 +4107,13 @@ GhcUnregisterised=YES
To support GHCi, you need to port the dynamic linker
(fptools/ghc/rts/Linker.c). The linker
currently supports the ELF and PEi386 object file formats - if
- your platform uses one of these then you probably don't have
- to do anything except fiddle with the
- #ifdefs at the top of
- Linker.c to tell it about your OS.
+ your platform uses one of these then things will be
+ significantly easier. The majority of Unix platforms use the
+ ELF format these days. Even so, there are some
+ machine-specific parts of the ELF linker: for example, the
+ code for resolving particular relocation types is
+ machine-specific, so some porting of this code to your
+ architecture will probaly be necessary.
If your system uses a different object file format, then
you have to write a linker — good luck!
@@ -3718,7 +4310,7 @@ Workaround: don't put weird things in string args to cpp macr
-Notes for building under Windows
+Notes for building under Windows
This section summarises how to get the utilities you need on your
@@ -3730,38 +4322,507 @@ guide) before continuing to read these notes.
-Before you start
+Cygwin and MinGW
+
+ The Windows situation for building GHC is rather confusing. This section
+tries to clarify, and to establish terminology.
+
+GHC-mingw
+MinGW (Minimalist GNU for Windows)
+is a collection of header
+files and import libraries that allow one to use gcc and produce
+native Win32 programs that do not rely on any third-party DLLs. The
+current set of tools include GNU Compiler Collection (gcc), GNU Binary
+Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
+other utilities.
+
+The GHC that we distribute includes, inside the distribution itself, the MinGW gcc,
+as, ld, and a bunch of input/output libraries.
+GHC compiles Haskell to C (or to
+assembly code), and then invokes these MinGW tools to generate an executable binary.
+The resulting binaries can run on any Win32 system.
+
+ We will call a GHC that targets MinGW in this way GHC-mingw.
+
+ The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
+Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
+library; they have to do
+their input output using standard Haskell I/O libraries, or native Win32 bindings.
+
+
+
+GHC-cygwin
+
+There is a way to get the full Posix interface, which is to use Cygwin.
+Cygwin is a complete Unix simulation that runs on Win32.
+Cygwin comes with a shell, and all the usual Unix commands: mv, rm,
+ls, plus of course gcc, ld and so on.
+A C program compiled with the Cygwin gcc certainly can use all of Posix.
+
+So why doesn't GHC use the Cygwin gcc and libraries? Because
+Cygwin comes with a DLL that must be linked with every runnable Cygwin-compiled program.
+A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
+If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
+that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
+Worse, Cygwin is a moving target. The name of the main DLL, cygwin1.dll
+does not change, but the implementation certainly does. Even the interfaces to functions
+it exports seem to change occasionally. So programs compiled by GHC might only run with
+particular versions of Cygwin. All of this seems very undesirable.
+
+
+Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
+we will call that GHC-cygwin. The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+
+
+
+HOST_OS vs TARGET_OS
+
+
+In the source code you'll find various ifdefs looking like:
+
+ #ifdef mingw32_HOST_OS
+ ...blah blah...
+ #endif
+
+and
+
+ #ifdef mingw32_TARGET_OS
+ ...blah blah...
+ #endif
+
+These macros are set by the configure script (via the file config.h).
+Which is which? The criterion is this. In the ifdefs in GHC's source code:
+
+
+ The "host" system is the one on which GHC itself will be run.
+
+
+ The "target" system is the one for which the program compiled by GHC will be run.
+
+
+For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
+So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+
+
+
+
+Summary
+
+Notice that "GHC-mingw" means "GHC that targets MinGW". It says nothing about
+how that GHC was built. It is entirely possible to have a GHC-mingw that was built
+by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.
+
+We distribute only a GHC-mingw built by a GHC-mingw; supporting
+GHC-cygwin too is beyond our resources. The GHC we distribute
+therefore does not require Cygwin to run, nor do the programs it
+compiles require Cygwin.
+
+The instructions that follow describe how to build GHC-mingw. It is
+possible to build GHC-cygwin, but it's not a supported route, and the build system might
+be flaky.
+
+In your build tree, you build a compiler called ghc-inplace. It
+uses the gcc that you specify using the
+ flag when you run
+configure (see below).
+The makefiles are careful to use ghc-inplace (not gcc)
+to compile any C files, so that it will in turn invoke the right gcc rather that
+whatever one happens to be in your path. However, the makefiles do use whatever ld
+and ar happen to be in your path. This is a bit naughty, but (a) they are only
+used to glom together .o files into a bigger .o file, or a .a file,
+so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
+Cygwin and Mingw use the same .o file format. So its ok.
+
+
+
+
+Installing and configuring Cygwin
+
+You don't need Cygwin to use GHC,
+but you do need it to build GHC.
+
+ Install Cygwin from http://www.cygwin.com/.
+The installation process is straightforward; we install it in c:/cygwin.
+During the installation dialogue, make sure that you select all of the following:
+
+
+ cvs,
+
+
+ openssh,
+
+
+ autoconf,
+
+
+ automake,
+
+
+ binutils (includes ld and (I think) ar),
+
+
+ gcc,
+
+
+ flex,
+
+
+ make.
+
+
+If you miss out any of these, strange things will happen to you. To see thse packages,
+click on the "View" button in the "Select Packages"
+stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
+"Category" isn't very helpful, and the "View" button is rather unobtrousive.
+
+ Now set the following user environment variables:
+
+ Add c:/cygwin/bin and c:/cygwin/usr/bin to your
+PATH
+
-Make sure that the user environment variable
-MAKE_MODE is set to UNIX. If you
+Set MAKE_MODE to UNIX. If you
don't do this you get very weird messages when you type
-make, such as:
+make, such as:
/c: /c: No such file or directory
+ Set SHELL to
+c:/cygwin/bin/bash. When you invoke a shell in Emacs, this
+SHELL is what you get.
+
+
+ Set HOME to point to your
+home directory. This is where, for example,
+bash will look for your .bashrc
+file. Ditto emacs looking for .emacsrc
+
+
+
+
+
+There are a few other things to do:
+
+
+
+By default, cygwin provides the command shell ash
+as sh.exe. We have often seen build-system problems that
+turn out to be due to bugs in ash
+(to do with quoting
+and length of command lines). On the other hand bash seems
+to be rock solid.
+So, in cygwin/bin
+remove the supplied sh.exe (or rename it as ash.exe),
+and copy bash.exe to sh.exe.
+You'll need to do this in Windows Explorer or the Windows cmd shell, because
+you can't rename a running program!
+
+
+
+
+
+Some script files used in the make system start with "#!/bin/perl",
+(and similarly for sh). Notice the hardwired path!
+So you need to ensure that your /bin directory has the following
+binaries in it:
+
+sh
+perl
+cat
+
+All these come in Cygwin's bin directory, which you probably have
+installed as c:/cygwin/bin. By default Cygwin mounts "/" as
+c:/cygwin, so if you just take the defaults it'll all work ok.
+(You can discover where your Cygwin
+root directory / is by typing mount.)
+Provided /bin points to the Cygwin bin
+directory, there's no need to copy anything. If not, copy these binaries from the cygwin/bin
+directory (after fixing the sh.exe stuff mentioned in the previous bullet).
+
+
+
+
+
+Finally, here are some things to be aware of when using Cygwin:
+
+Cygwin doesn't deal well with filenames that include
+spaces. "Program Files" and "Local files" are
+common gotchas.
+
+
+ Cygwin implements a symbolic link as a text file with some
+magical text in it. So other programs that don't use Cygwin's
+I/O libraries won't recognise such files as symlinks.
+In particular, programs compiled by GHC are meant to be runnable
+without having Cygwin, so they don't use the Cygwin library, so
+they don't recognise symlinks.
+
+
+
+Win32 has a find command which is not the same as Cygwin's find.
+You will probably discover that the Win32 find appears in your PATH
+before the Cygwin one, because it's in the systemPATH
+environment variable, whereas you have probably modified the userPATH
+variable. You can always invoke find with an absolute path, or rename it.
+
+
+
+
+
+
+Configuring SSH
+
+ssh comes with Cygwin, provided you remember to ask for it when
+you install Cygwin. (If not, the installer lets you update easily.) Look for openssh
+(not ssh) in the Cygwin list of applications!
+
+There are several strange things about ssh on Windows that you need to know.
+
+
+
+ The programs ssh-keygen1, ssh1, and cvs,
+ seem to lock up bash entirely if they try to get user input (e.g. if
+ they ask for a password). To solve this, start up cmd.exe
+ and run it as follows:
+
+ c:\tmp> set CYGWIN32=tty
+ c:\tmp> c:/user/local/bin/ssh-keygen1
+
+
+
+
+ssh needs to access your directory .ssh, in your home directory.
+To determine your home directory ssh first looks in
+c:/cygwin/etc/passwd (or wherever you have Cygwin installed). If there's an entry
+there with your userid, it'll use that entry to determine your home directory, ignoring
+the setting of the environment variable $HOME. If the home directory is
+bogus, ssh fails horribly. The best way to see what is going on is to say
+
+ ssh -v cvs.haskell.org
+
+which makes ssh print out information about its activity.
+
+ You can fix this problem, either by correcting the home-directory field in
+c:/cygwin/etc/passwd, or by simply deleting the entire entry for your userid. If
+you do that, ssh uses the $HOME environment variable instead.
+
+
+
+
+
+ To protect your
+ .ssh from access by anyone else,
+ right-click your .ssh 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!
+
+
+
+ In fact ssh 3.6.1 now seems to require
+ you to have Unix permissions 600 (read/write for owner only)
+ on the .ssh/identity file, else it
+ bombs out. For your local C drive, it seems that chmod 600 identity works,
+ but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
+ The solution seems to be to set the $CYGWIN environment
+ variable to "ntsec neta". The $CYGWIN environment variable is discussed
+ in the Cygwin User's Guide,
+ and there are more details in the Cygwin FAQ.
+
+
+
+
+
+
+Other things you need to install
+
+You have to install the following other things to build GHC:
+
+
+
+Install an executable GHC, from http://www.haskell.org/ghc.
+This is what you will use to compile GHC. Add it in your
+PATH: the installer tells you the path element
+you need to add upon completion.
+
+
+
+
+
+Install an executable Happy, from http://www.haskell.org/happy.
+Happy is a parser generator used to compile the Haskell grammar. Add it in your
+PATH.
+
+
+
+
+ Install Alex. This can be done by building from the
+ source distribution in the usual way. Sources are
+ available from http://www.haskell.org/alex.
+
+
GHC uses the mingw C compiler to
-generate code, so you have to install that. Just pick up a mingw bundle at
+generate code, so you have to install that (see ).
+Just pick up a mingw bundle at
http://www.mingw.org/.
We install it in c:/mingw.
+Do not add any of the mingw binaries to your path.
+They are only going to get used by explicit access (via the --with-gcc flag you
+give to configure later). If you do add them to your path
+you are likely to get into a mess because their names overlap with Cygwin binaries.
+
+
+
+
+
+We use emacs a lot, so we install that too.
+When you are in fptools/ghc/compiler, you can use
+"make tags" to make a TAGS file for emacs. That uses the utility
+fptools/ghc/utils/hasktags/hasktags, so you need to make that first.
+The most convenient way to do this is by going make boot in fptools/ghc.
+The make tags command also uses etags, which comes with emacs,
+so you will need to add emacs/bin to your PATH.
+
+
+
+ Finally, check out a copy of GHC sources from
+the CVS repository, following the instructions above ().
+
+
+
+
+
+
+Building GHC
+
+OK!
+Now go read the documentation above on building from source ();
+the bullets below only tell
+you about Windows-specific wrinkles.
+
-Install a version of GHC, and put it in your
-PATH (the installer tells you the path element
-you need to add upon completion.)
+Run autoconf both in fptools
+and in fptools/ghc. If you omit the latter step you'll
+get an error when you run ./configure:
+
+...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
+
-
-
+
+autoconf seems to create the file configure
+read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
+you get
+
+/usr/bin/autoconf: cannot create configure: permission denied
+
+Solution: delete configure first.
+
+
+
+
+You either need to add ghc to your
+PATH before you invoke
+configure, or use the configure
+option .
+
+
+
+
+If you are paranoid, delete config.cache if it exists.
+This file occasionally remembers out-of-date configuration information, which
+can be really confusing.
+
+
+
+
+
+ After autoconf run ./configure in
+ fptools/ thus:
+
+
+ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
+
+This is the point at which you specify that you are building GHC-mingw
+(see ).
+
+ Both these options are important! It's possible to get into
+trouble using the wrong C compiler!
+
+Furthermore, it's very important that you specify a
+full MinGW path for gcc, not a Cygwin path, because GHC (which
+uses this path to invoke gcc) is a MinGW program and won't
+understand a Cygwin path. For example, if you
+say --with-gcc=/mingw/bin/gcc, it'll be interpreted as
+/cygdrive/c/mingw/bin/gcc, and GHC will fail the first
+time it tries to invoke it. Worse, the failure comes with
+no error message whatsoever. GHC simply fails silently when first invoked,
+typically leaving you with this:
+
+make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
+../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
+ -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
+ -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
+ -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
+ -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
+ -optc-fomit-frame-pointer -O2 -static
+ -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
+make[2]: *** [Adjustor.o] Error 1
+make[1]: *** [all] Error 1
+make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
+make: *** [all] Error 1
+
+Be warned!
+
+
+
+If you want to build GHC-cygwin ()
+you'll have to do something more like:
+
+ ./configure --with-gcc=...the Cygwin gcc...
+
+
+
+
+ You almost certainly want to set
+
+ SplitObjs = NO
+
+in your build.mk configuration file (see ).
+This tells the build system not to split each library into a myriad of little object files, one
+for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
+it dramatically increases the time taken to build the libraries in the first place.
+
+
+
+ Do not attempt to build the documentation.
+It needs all kinds of wierd Jade stuff that we haven't worked out for
+Win32.
+
+
+