X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=9b21ea60197041035145d82a285d8cd31de9ac8c;hb=776afe7766a4fe991dbb5a38595900ebd95d4d5a;hp=1fa1656520427832e7d8460c034f4774066ce636;hpb=feaf38913aefbc81cfe991a622820931f186e02d;p=ghc-hetmet.git
diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index 1fa1656..9b21ea6 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
@@ -1116,6 +1122,14 @@ $ cvs checkout nofib/spectral
+ mips64-sgi-irix6
+ mips-sgi-irix6
+
+ GHC currently works unregisterised.
+
+
+
+ powerpc-ibm-aixpowerpc-ibm-aix
@@ -1284,23 +1298,24 @@ $ cvs checkout nofib/spectral
- Autoconf
- pre-supposed: Autoconf
- Autoconf, pre-supposed
+ autoconf
+ pre-supposed: autoconf
+ autoconf, pre-supposed
- GNU Autoconf is needed if you intend to build from the
+ 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.
- Version 2.52 or later of autoconf is required.
- NB. vesrion 2.13 will no longer work, as of GHC version
+ 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.
- Autoconf builds the configure
- script from configure.ac and
- aclocal.m4. If you modify either of
- these files, you'll need autoconf to
- rebuild configure.
+ 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.
@@ -1420,7 +1435,8 @@ $ cvs checkout nofib/spectral
want a completely standard build, then the following should
work:
-$ ./configure
+$ autoreconf
+$ ./configure
$ make
$ make install
@@ -1591,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.ac
+ 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.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.ac) 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.
@@ -1714,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.
@@ -1885,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)
-
@@ -4296,24 +4303,19 @@ Workaround: don't put weird things in string args to cpp macr
-Notes for building under Windows
-
+Platforms, scripts, and file names
-This section summarises how to get the utilities you need on your
-Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
-installing and running GHC may be found in the user guide. In general,
-Win95/Win98 behave the same, and WinNT/Win2k behave the same.
-You should read the GHC installation guide sections on Windows (in the user
-guide) before continuing to read these notes.
+GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
+gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
+Windows platforms: Cygwin, MSYS, and MinGW
-Cygwin and MinGW
-
- The Windows situation for building GHC is rather confusing. This section
+ The build system is built around Unix-y makefiles. Because it's not native,
+the Windows situation for building GHC is particularly confusing. This section
tries to clarify, and to establish terminology.
-GHC-mingw
+MinGWMinGW (Minimalist GNU for Windows)
is a collection of header
@@ -4323,43 +4325,121 @@ current set of tools include GNU Compiler Collection (gcc), G
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.
+
+ The down-side of MinGW is that the MinGW libraries do not support anything like the full
+Posix interface.
- We will call a GHC that targets MinGW in this way GHC-mingw.
+
+
+Cygwin and MSYS
+
+You can't use the MinGW to build GHC, because MinGW doesn't have a shell,
+or the standard Unix commands such as mv, rm,
+ls, nor build-system stuff such as make and cvs.
+For that, there are two choices: Cygwin
+and MSYS:
+
+
+
+Cygwin comes with compilation tools (gcc, ld and so on), which
+compile code that has access to all of Posix. The price is that the executables must be
+dynamically linked with the Cygwin DLL, so that you cannot run a Cywin-compiled program on a machine
+that doesn't have Cygwin. 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.
+
- 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
+
+MSYS is a fork of the Cygwin tree, so they
+are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
+through fewer layers, so MSYS is quite a bit faster too.
+
+
+Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
+compile binaries that run with no DLL support, on any Win32 system.
+However, MSYS does come with all the make-system tools, such as make, autoconf,
+cvs, ssh etc. To get these, you have to download the
+MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
+
+MSYS does have a DLL, but it's only used by MSYS commands (sh, rm,
+ssh and so on),
+not by programs compiled under MSYS.
+
+
+
+
+
+
+
+Targeting MinGW
+
+We want GHC to compile programs that work on any Win32 system. Hence:
+
+
+GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
+invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
+will work on any system, but it also means that the programs GHC compiles do not have access
+to all of Posix. In particular, they cannot import the (Haskell) Posix
library; they have to do
-their input output using standard Haskell I/O libraries, or native Win32 bindings.
+their input output using standard Haskell I/O libraries, or native Win32 bindings.
+ We will call a GHC that targets MinGW in this way GHC-mingw.
+
+
+
+To make the GHC distribution self-contained, the GHC distribution includes the MinGW gcc,
+as, ld, and a bunch of input/output libraries.
+
+
+So GHC targets MinGW, not Cygwin.
+It is in principle possible to build a version of GHC, GHC-cygwin,
+that targets Cygwin instead. The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+We do not support GHC-cygwin, however; it is beyond our resources.
+
+
+While GHC targets MinGW, that says nothing about
+how GHC is built. We use both MSYS and Cygwin as build environments for
+GHC; both work fine, though MSYS is rather lighter weight.
+
+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 correct 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.
-GHC-cygwin
+ File names
-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.
+Cygwin, MSYS, and the underlying Windows file system all understand file paths of form c:/tmp/foo.
+However:
+
+
+MSYS programs understand /bin, /usr/bin, and map Windows's lettered drives as
+/c/tmp/foo etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
-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.
+ When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS /bin
+directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
+arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
+if you invoke
+
+ foogle -B/c/tmp/baz
+
+the MSYS shell will actually call foogle with argument -Bc:/tmp/baz.
+
+
+
+Cygwin programs have a more complicated mount table, and map the lettered drives as /cygdrive/c/tmp/foo.
-
-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.
+The Cygwin shell does no argument processing when invoking non-Cygwin programs.
+
+
@@ -4394,51 +4474,151 @@ So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp ma
-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.
+Wrapper scripts
-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.
+
+Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
+For installed programs, the strategy depends on the platform. We'll use
+GHC itself as an example:
+
+
+ On Unix, the command ghc is a shell script, generated by adding installation
+ paths to the front of the source file ghc.sh,
+ that invokes the real binary, passing "-Bpath" as an argument to tell ghc
+ where to find its supporting files.
+
-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.
+
+ On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
+ native Windows shell cmd (e.g. limits on the length
+ of the command line). So instead we invoke the GHC binary directly, with no -B flag.
+ GHC uses the Windows getExecDir function to find where the executable is,
+ and from that figures out where the supporting files are.
+
+
+(You can find the layout of GHC's supporting files in the
+ section "Layout of installed files" of Section 2 of the GHC user guide.)
+
+
+Things work differently for in-place execution, where you want to
+execute a program that has just been built in a build tree. The difference is that the
+layout of the supporting files is different.
+In this case, whether on Windows or Unix, we always use a shell script. This works OK
+on Windows because the script is executed by MSYS or Cygwin, which don't have the
+shortcomings of the native Windows cmd shell.
+
-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.
+
+
+
+
+Instructions for building under Windows
+
+
+This section gives detailed instructions for how to build
+GHC from source on your Windows machine. Similar instructions for
+installing and running GHC may be found in the user guide. In general,
+Win95/Win98 behave the same, and WinNT/Win2k behave the same.
+
+
+Make sure you read the preceding section on platforms ()
+before reading section.
+
+
+
+Installing and configuring MSYS
+
+
+MSYS is a lightweight alternative to Cygwin.
+You don't need MSYS to use GHC,
+but you do need it or Cygwin to build GHC.
+Here's how to install MSYS.
+
+
+Go to http://www.mingw.org/download.shtml and
+download the following (of course, the version numbers will differ):
+
+ The main MSYS package (binary is sufficient): MSYS-1.0.9.exe
+
+ The MSYS developer's toolkit (binary is sufficient): msysDTK-1.0.1.exe.
+ This provides make, autoconf,
+ ssh, cvs and probably more besides.
+
+
+Run both executables (in the order given above) to install them. I put them in c:/msys
+
+
+
+Set the following environment variables
+
+ PATH: add c:/msys/1.0/bin to your path. (Of course, the version number may differ.)
+
+
+ HOME: set to your home directory (e.g. c:/userid).
+ This is where, among other things, ssh will look for your .ssh directory.
+
+
+ SHELL: set to c:/msys/1.0/bin/sh.exe
+
+
+ CVS_RSH: set to c:/msys/1.0/bin/ssh.exe. Only necessary if
+ you are using CVS.
+
+
+ MAKE_MODE: set to UNIX. (I'm not certain this is necessary for MSYS.)
+
+
+
+
+
+
+Check that the CYGWIN environment variable is not set. It's a bad bug
+that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
+causes the MSYS ssh to bogusly fail complaining that your .ssh/identity
+file has too-liberal permissinos.
+
+
+
-
Installing and configuring CygwinYou don't need Cygwin to use GHC,
-but you do need it to build GHC.
+but you do need it or MSYS 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:
@@ -4458,7 +4638,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.
@@ -4540,6 +4720,7 @@ variable. You can always invoke find with an absolute path,
+
Configuring SSHssh comes with Cygwin, provided you remember to ask for it when
@@ -4680,9 +4861,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
@@ -4695,8 +4875,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
@@ -4722,7 +4902,7 @@ can be really confusing.
- After autoconf run ./configure in
+ After autoreconf run ./configure in
fptools/ thus: