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-aix powerpc-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 +MinGW MinGW (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 Cygwin You 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 SSH ssh 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: