X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=inline;f=docs%2Fbuilding%2Fbuilding.sgml;h=9765ba32c27cc3e3e2fb4189b557b75a1800e0e3;hb=21bc88b56b77ef9160b415917245b2e69e2fd84c;hp=071f4c94fdbc54ef5ca3fea7ec7bbc77f07bcc84;hpb=711a6e963883e2a84ccfd878806651144dae353a;p=ghc-hetmet.git
diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index 071f4c9..9765ba3 100644
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -240,24 +240,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!
@@ -446,6 +432,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 installed, you need to check it out
+ as well.
@@ -481,7 +471,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:
@@ -564,17 +561,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
@@ -1142,6 +1147,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
@@ -1178,6 +1200,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.
+
+ GCC 3.3 currently cannot be used to build GHC, due to
+ some problems with the new C preprocessor.
+
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
@@ -1209,7 +1237,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.
@@ -1225,6 +1253,10 @@ $ 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
aclocal.m4. If you modify either of
@@ -1266,7 +1298,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
@@ -1342,6 +1374,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
@@ -1495,6 +1547,9 @@ $ 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
@@ -1517,12 +1572,6 @@ $ cvs checkout nofib/spectral
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.
@@ -1677,6 +1726,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:
@@ -1865,7 +1917,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.
@@ -2078,7 +2215,7 @@ 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.
@@ -3464,10 +3601,10 @@ $ make install-docs
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 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.HC files are architecture-dependent (but not
OS-dependent), so you have to get a set that were generated on
@@ -3589,11 +3726,11 @@ GhcWithRegisterised=NO
-# build.mk for GHC 5.xx
+# build.mk for GHC 5.xx and 6.x
GhcUnregisterised=YES
- Version 5.xx only: use the option
+ Versions 5.xx and 6.x only: use the option
instead of
when running
./configure.
@@ -3955,7 +4092,7 @@ guide) before continuing to read these notes.
-Cygwin and MinGW
+Cygwin and MinGW The Windows situation for building GHC is rather confusing. This section
tries to clarify, and to establish terminology.
@@ -4010,6 +4147,37 @@ that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix libr
+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.
+
+
+
+
SummaryNotice that "GHC-mingw" means "GHC that targets MinGW". It says nothing about
@@ -4047,9 +4215,13 @@ 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.
-Both cvs and ssh
-come with Cygwin, but you'll need them, so make sure you select them when running
-the Cygwin installer.
+During the installation dialogue, make sure that you select:
+cvs, openssh,
+autoconf,
+binutils (includes ld and (I think) ar),
+gcc,
+flex,
+make.
Now set the following user environment variables:
@@ -4087,8 +4259,24 @@ 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 bash). Notice the hardwired path!
+(and similarly for sh). Notice the hardwired path!
So you need to ensure that your /bin directory has the following
binaries in it:
@@ -4100,21 +4288,10 @@ All these come in Cygwin's bin directory, which you probabl
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).
+root directory / is by typing mount.)
Provided /bin points to the Cygwin bin
-directory, there's no need to copy anything.
-
-
-
-
-
-By default, cygwin provides the command shell ash
-as sh.exe. It has a couple of 'issues' (to do with quoting
-and length of command lines), so
-in your /bin directory, make sure that
-bash.exe is also provided as sh.exe
-(i.e. overwrite the old sh.exe with a copy of
-bash.exe).
+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).
@@ -4147,6 +4324,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:
@@ -4171,7 +4415,8 @@ Happy is a parser generator used to compile the Haskell grammar. Add it in your
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.
@@ -4184,6 +4429,18 @@ you are likely to get into a mess because their names overlap with Cygwin binari
+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 ().
@@ -4247,13 +4504,39 @@ can be really confusing.
fptools/ thus:
- ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc
+ ./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 ).
+(see ).
-Both these options are important! It's possible to get into
+ 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 ()
@@ -4264,6 +4547,17 @@ you'll have to do something more like:
+ 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.