X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=65db19cb41549682b3eb1d0b92b6a70bb21cb10a;hb=59df6a264461547a9672ad4a786cc706bcf60fd7;hp=3163611a175129e35d2f452977a572768d155fc5;hpb=a20ec0ced36bca7cd0594528922dbe31a6186eae;p=ghc-hetmet.git
diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index 3163611..65db19c 100644
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -4303,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
@@ -4330,43 +4325,106 @@ 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:
+
+
+
+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.
+
+
+
+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.
+
+In contrast, 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.
+
+
+
- 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
+ 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;
+The Cygwin shell does no argument processing when invoking non-Cygwin programs.
+
+
+
+
+
+
+Building GHC on Windows
+
+Targeting MinGW
+
+We want the GHC that we distribute to 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.
+ 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.
+
+
+
+It is in principle possible to build a version of GHC that targets Cygwin instead of MinGW;
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.
+We do not support this build route, however.
@@ -4431,6 +4489,56 @@ Cygwin and Mingw use the same .o file format. So its ok.
+Wrapper scripts
+
+
+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.
+
+
+
+ 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.
+
+
+
+
+
+
+Notes for building under Windows
+
+
+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.
+
+
+
Installing and configuring Cygwin
You don't need Cygwin to use GHC,