X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=3163611a175129e35d2f452977a572768d155fc5;hb=c53eacfc26ad223d987327c387624d2108d1a2db;hp=bcf3cf4f756ed5c272e9d682d6b3cb13157ef984;hpb=11f88ccab7c566d7f4d709edb387ee4bc7d52aa7;p=ghc-hetmet.git
diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index bcf3cf4..3163611 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,34 +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!
- [March 2003] 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.
-
@@ -456,6 +438,10 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument
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.
@@ -491,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:
@@ -574,7 +567,7 @@ $ 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
@@ -733,6 +726,17 @@ $ cvs checkout nofib/spectral
+ alex
+ alex
+ project
+
+ The Alex lexical
+ analyser generator for Haskell.
+
+
+
+ ghcghcproject
@@ -754,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.
@@ -1002,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
@@ -1082,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.
@@ -1100,6 +1122,14 @@ $ cvs checkout nofib/spectral
+ mips64-sgi-irix6
+ mips-sgi-irix6
+
+ GHC currently works unregisterised.
+
+
+
+ powerpc-ibm-aixpowerpc-ibm-aix
@@ -1114,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.
@@ -1213,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)
@@ -1244,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.
@@ -1252,19 +1285,37 @@ $ cvs checkout nofib/spectral
- Autoconf
- pre-supposed: Autoconf
- Autoconf, pre-supposed
+ Alex
+ Alex
- GNU Autoconf is needed if you intend to build from the
+ 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.
+
+
+
+
+ autoconf
+ pre-supposed: autoconf
+ autoconf, pre-supposed
+
+ GNU autoconf is needed if you intend to build from the
CVS sources, it is not needed if you
just intend to build a standard source distribution.
- Autoconf builds the configure
- script from configure.in and
- aclocal.m4. If you modify either of
- these files, you'll need autoconf to
- rebuild configure.
+ Version 2.52 or later of the autoconf package is required.
+ NB. version 2.13 will no longer work, as of GHC version
+ 6.1.
+
+ autoreconf (from the autoconf package)
+ recursively builds configure scripts from
+ the corresponding configure.ac and
+ aclocal.m4 files. If you modify one of
+ the latter files, you'll need autoreconf to
+ rebuild the corresponding configure.
@@ -1301,7 +1352,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
@@ -1384,7 +1435,8 @@ $ cvs checkout nofib/spectral
want a completely standard build, then the following should
work:
-$ ./configure
+$ autoreconf
+$ ./configure
$ make
$ make install
@@ -1418,7 +1470,7 @@ $ make install
- configure.in,
+ configure.ac,
config.sub,
config.guess: these files support the
configuration process.
@@ -1441,7 +1493,7 @@ $ make install
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.
@@ -1555,26 +1607,32 @@ $ make install
Change directory to
$(FPTOOLS_TOP) and
- issue the command
- autoconfautoconf
- (with no arguments). This GNU program converts
- $(FPTOOLS_TOP)/configure.in
+ issue the command
+
+autoreconf
+
+ autoreconf
+ (with no arguments). This GNU program (recursively) converts
+ $(FPTOOLS_TOP)/configure.ac and
+ $(FPTOOLS_TOP)/aclocal.m4
to a shell script called
$(FPTOOLS_TOP)/configure.
+ If autoreconf bleats that it can't write the file configure,
+ then delete the latter and try again. Note that you must use autoreconf,
+ and not the old autoconf! If you erroneously use the latter, you'll get
+ a message like "No rule to make target 'mk/config.h.in'".
- Some projects, including GHC, have their own
- configure script. If there's an
- $(FPTOOLS_TOP)/<project>/configure.in,
- 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
- be short, although the resulting shell script,
- configure, and
- mk/config.h.in, are long.
+ Some projects, including GHC, have their own configure script.
+ autoreconf takes care of that, too, so all you have
+ to do is calling autoreconf in the top-level directory
+ $(FPTOOLS_TOP).
+
+ These steps are completely platform-independent; they just mean
+ that the human-written files (configure.ac and
+ aclocal.m4) can be short, although the resulting
+ files (the configure shell scripts and the C header
+ template mk/config.h.in) are long.
@@ -1592,7 +1650,7 @@ $ make install
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
@@ -1678,13 +1736,6 @@ $ make install
-
- 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.
@@ -1772,17 +1823,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
@@ -1849,21 +1900,13 @@ $ cd /scratch/joe-bloggs/myfptools-sun4
Prepare for system configuration:
-$ autoconf
+$ autoreconf
(You can skip this step if you are starting from a
source distribution, and you already have
configure and
mk/config.h.in.)
-
- Some projects, including GHC itself, have their own
- configure scripts, so it is necessary to run autoconf again
- in the appropriate subdirectories. eg:
-
-
-$ (cd ghc; autoconf)
-
@@ -2224,7 +2267,8 @@ Foo.o : Baz.hi
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.
@@ -3604,17 +3648,16 @@ $ make install-docs
target machine, and compiling them using gcc to get a working
GHC.
- NOTE: GHC versions 5.xx and later are
- significantly harder to bootstrap from C than earlier 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:
@@ -3698,65 +3741,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 and 6.x
-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
+
- Versions 5.xx and 6.x 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.
+
+
+
@@ -3883,10 +4100,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!
@@ -4218,14 +4438,34 @@ 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:
-cvs, openssh,
-autoconf,
-binutils (includes ld and (I think) ar),
-gcc,
-flex,
-make.
-
+During the installation dialogue, make sure that you select all of the following:
+
+
+ cvs,
+
+
+ openssh,
+
+
+ autoconf,
+
+
+ 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:
@@ -4245,7 +4485,7 @@ don't do this you get very weird messages when you type
Set SHELL to
-c:/cygwin/bin/sh. When you invoke a shell in Emacs, this
+c:/cygwin/bin/bash. When you invoke a shell in Emacs, this
SHELL is what you get.
@@ -4327,6 +4567,73 @@ variable. You can always invoke find with an absolute path,
+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 installYou have to install the following other things to build GHC:
@@ -4348,6 +4655,12 @@ Happy is a parser generator used to compile the Haskell grammar. Add it in your
+
+ 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
@@ -4394,9 +4707,8 @@ you about Windows-specific wrinkles.
-Run autoconf both in fptools
-and in fptools/ghc. If you omit the latter step you'll
-get an error when you run ./configure:
+If you used autoconf instead of autoreconf,
+you'll get an error when you run ./configure:
...lots of stuff...
creating mk/config.h
@@ -4409,8 +4721,8 @@ 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),
+autoreconf seems to create the file configure
+read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
you get
/usr/bin/autoconf: cannot create configure: permission denied
@@ -4436,7 +4748,7 @@ can be really confusing.
- After autoconf run ./configure in
+ After autoreconf run ./configure in
fptools/ thus: