X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=bd5246c598cf56cd7461655577c95f2a0a60adcc;hp=b01aad7dba3b9702e745916a5d08bf5742793d91;hb=cab3c5cb1a0038412472172cb0b25bc81dfdde8f;hpb=c7867b137716d1c3abca59853c382dab190af527 diff --git a/docs/building/building.sgml b/docs/building/building.sgml index b01aad7..bd5246c 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! @@ -437,14 +423,19 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument the fpconfig bit. $ cd directory - $ cvs checkout ghc hslibs + $ cvs checkout ghc hslibs libraries The second command here checks out the relevant modules you want to work on. For a GHC build, for instance, - you need at least the ghc and - hslibs modules (for a full list of the - projects available, see ). + you need at least the ghc, + 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. @@ -480,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: @@ -563,17 +561,25 @@ $ cvs commit -F commit-message directory 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 @@ -735,11 +741,11 @@ $ cvs checkout nofib/spectral - green-card - green-cardproject + greencard + greencardproject The Green Card + url="http://www.haskell.org/greencard/">GreenCard system for generating Haskell foreign function interfaces. @@ -1060,6 +1066,15 @@ $ cvs checkout nofib/spectral + ia64-unknown-linux + ia64-unknown-linux + + GHC currently works unregisterised. A registerised + port is in progress. + + + + mips-sgi-irix5 mips-sgi-irix[5-6] @@ -1132,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. + + + + Perl pre-supposed: Perl Perl, pre-supposed @@ -1168,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 @@ -1199,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. @@ -1215,8 +1253,12 @@ $ 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 + script from configure.ac and aclocal.m4. If you modify either of these files, you'll need autoconf to rebuild configure. @@ -1256,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 @@ -1286,46 +1328,6 @@ $ cvs checkout nofib/spectral - - Tools for building the Documentation - - The following additional tools are required if you want to - format the documentation that comes with the - fptools projects: - - - - DocBook - pre-supposed: DocBook - DocBook, pre-supposed - - All our documentation is written in SGML, using the - DocBook DTD. Instructions on installing and configuring - the DocBook tools are in the installation guide (in the - GHC user guide). - - - - - TeX - pre-supposed: TeX - TeX, pre-supposed - - A decent TeX distribution is required if you want to - produce printable documentation. We recomment teTeX, - which includes just about everything you need. - - - - - In order to actually build any documentation, you need to - set SGMLDocWays in your - build.mk. Valid values to add to this list - are: dvi, ps, - pdf, html, and - rtf. - - Other useful tools @@ -1343,6 +1345,10 @@ $ cvs checkout nofib/spectral + + More tools are required if you want to format the documentation + that comes with GHC and other fptools projects. See . @@ -1368,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 @@ -1389,7 +1415,7 @@ $ cvs checkout nofib/spectral - configure.in, + configure.ac, config.sub, config.guess: these files support the configuration process. @@ -1412,7 +1438,7 @@ $ cvs checkout nofib/spectral 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. @@ -1521,34 +1547,31 @@ $ 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 autoconfautoconf (with no arguments). This GNU program converts - $(FPTOOLS_TOP)/configure.in + $(FPTOOLS_TOP)/configure.ac to a shell script called $(FPTOOLS_TOP)/configure. Some projects, including GHC, have their own configure script. If there's an - $(FPTOOLS_TOP)/<project>/configure.in, + $(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.in) can + human-written file (configure.ac) can 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. @@ -1566,7 +1589,7 @@ $ cvs checkout nofib/spectral 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 @@ -1703,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: @@ -1743,17 +1769,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 @@ -1891,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. + + + + + bootstrap bootstrap2 + + 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. @@ -2104,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. @@ -3192,6 +3303,266 @@ $ make way=p + + Building the documentation + + + Tools for building the Documentation + + The following additional tools are required if you want to + format the documentation that comes with the + fptools projects: + + + + DocBook + pre-supposed: DocBook + DocBook, pre-supposed + + Much of our documentation is written in SGML, using + the DocBook DTD. Instructions on installing and + configuring the DocBook tools are below. + + + + + TeX + pre-supposed: TeX + TeX, pre-supposed + + A decent TeX distribution is required if you want to + produce printable documentation. We recomment teTeX, + which includes just about everything you need. + + + + + Haddock + Haddock + + + Haddock is a Haskell documentation tool that we use + for automatically generating documentation from the + library source code. It is an fptools + project in itself. To build documentation for the + libraries (fptools/libraries) you + should check out and build Haddock in + fptools/haddock. Haddock requires GHC + to build. + + + + + + + Installing the DocBook tools + + + Installing the DocBook tools on Linux + + If you're on a recent RedHat system (7.0+), you probably + have working DocBook tools already installed. The configure + script should detect your setup and you're away. + + If you don't have DocBook tools installed, and you are + using a system that can handle RedHat RPM packages, you can + probably use the Cygnus + DocBook tools, which is the most shrink-wrapped SGML + suite that we could find. You need all the RPMs except for + psgml (i.e. docbook, + jade, jadetex, + sgmlcommon and + stylesheets). Note that most of these + RPMs are architecture neutral, so are likely to be found in a + noarch directory. The SuSE RPMs also + work; the RedHat ones don't in RedHat 6.2 + (7.0 and later should be OK), but they are easy to fix: just + make a symlink from + /usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl + to /usr/lib/sgml/lib/dblib.dsl. + + + + Installing DocBook on FreeBSD + + On FreeBSD systems, the easiest way to get DocBook up + and running is to install it from the ports tree or a + pre-compiled package (packages are available from your local + FreeBSD mirror site). + + To use the ports tree, do this: + + $ cd /usr/ports/textproc/docproj + $ make install + + This installs the FreeBSD documentation project tools, which + includes everything needed to format the GHC + documentation. + + + + Installing from binaries on Windows + + It's a good idea to use Norman Walsh's installation + notes as a guide. You should get version 3.1 of + DocBook, and note that his file test.sgm + won't work, as it needs version 3.0. You should unpack Jade + into \Jade, along with the entities, + DocBook into \docbook, and the DocBook + stylesheets into \docbook\stylesheets (so + they actually end up in + \docbook\stylesheets\docbook). + + + + + Installing the DocBook tools from source + + + Jade + + Install OpenJade + (Windows binaries are available as well as sources). If you + want DVI, PS, or PDF then install JadeTeX from the + dsssl subdirectory. (If you get the + error: + + +! LaTeX Error: Unknown option implicit=false' for package hyperref'. + + + your version of hyperref is out of date; + download it from CTAN + (macros/latex/contrib/supported/hyperref), + and make it, ensuring that you have first removed or renamed + your old copy. If you start getting file not found errors + when making the test for hyperref, you + can abort at that point and proceed straight to + make install, or enter them as + ../filename.) + + Make links from virtex to + jadetex and + pdfvirtex to + pdfjadetex (otherwise DVI, PostScript + and PDF output will not work). Copy + dsssl/*.{dtd,dsl} and + catalog to + /usr/[local/]lib/sgml. + + + + DocBook and the DocBook stylesheets + + Get a Zip of DocBook + and install the contents in + /usr/[local/]/lib/sgml. + + Get the DocBook + stylesheets and install in + /usr/[local/]lib/sgml/stylesheets + (thereby creating a subdirectory docbook). For indexing, + copy or link collateindex.pl from the + DocBook stylesheets archive in bin into + a directory on your PATH. + + Download the ISO + entities into + /usr/[local/]lib/sgml. + + + + + + Configuring the DocBook tools + + Once the DocBook tools are installed, the configure script + will detect them and set up the build system accordingly. If you + have a system that isn't supported, let us know, and we'll try + to help. + + + + Remaining problems + + If you install from source, you'll get a pile of warnings + of the form + +DTDDECL catalog entries are not supported + + every time you build anything. These can safely be ignored, but + if you find them tedious you can get rid of them by removing all + the DTDDECL entries from + docbook.cat. + + + + Building the documentation + + To build documentation in a certain format, you can + say, for example, + + +$ make html + + + to build HTML documentation below the current directory. + The available formats are: dvi, + ps, pdf, + html, and rtf. Note that + not all documentation can be built in all of these formats: HTML + documentation is generally supported everywhere, and DocBook + documentation might support the other formats (depending on what + other tools you have installed). + + All of these targets are recursive; that is, saying + make html will make HTML docs for all the + documents recursively below the current directory. + + Because there are many different formats that the DocBook + documentation can be generated in, you have to select which ones + you want by setting the SGMLDocWays variable + to a list of them. For example, in + build.mk you might have a line: + + +SGMLDocWays = html ps + + + This will cause the documentation to be built in the requested + formats as part of the main build (the default is not to build + any documentation at all). + + + + Installing the documentation + + To install the documentation, use: + + +$ make install-docs + + + This will install the documentation into + $(datadir) (which defaults to + $(prefix)/share). The exception is HTML + documentation, which goes into + $(datadir)/html, to keep things tidy. + + Note that unless you set $(SGMLDocWays) + to a list of formats, the install-docs target + won't do anything for SGML documentation. + + + + + Porting GHC @@ -3230,10 +3601,10 @@ $ make way=p 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 @@ -3254,8 +3625,8 @@ $ make way=p corresponding Haskell source (.hs or .lhs) in the compiler subdirectory ghc/compiler and in the libraries - (ghc/lib, and subdirectories of - hslibs). + (subdirectories of hslibs and + libraries). @@ -3331,7 +3702,8 @@ foo% make install 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. + 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 @@ -3354,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. @@ -3708,7 +4080,7 @@ Workaround: don't put weird things in string args to cpp macr -Notes for building under Windows +Notes for building under Windows This section summarises how to get the utilities you need on your @@ -3720,38 +4092,478 @@ guide) before continuing to read these notes. -Before you start +Cygwin and MinGW + + The Windows situation for building GHC is rather confusing. This section +tries to clarify, and to establish terminology. + +GHC-mingw + + MinGW (Minimalist GNU for Windows) +is a collection of header +files and import libraries that allow one to use gcc and produce +native Win32 programs that do not rely on any third-party DLLs. The +current set of tools include GNU Compiler Collection (gcc), GNU Binary +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. + + We will call a GHC that targets MinGW in this way GHC-mingw. + + 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 + +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. + +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. + + +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. + + + +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. + + + + +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. + +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. + +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. + +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. + + + + +Installing and configuring Cygwin + +You don't need Cygwin to use GHC, +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. + + + Now set the following user environment variables: + + Add c:/cygwin/bin and c:/cygwin/usr/bin to your +PATH + -Make sure that the user environment variable -MAKE_MODE is set to UNIX. If you +Set MAKE_MODE to UNIX. If you don't do this you get very weird messages when you type -make, such as: +make, such as: /c: /c: No such file or directory + Set SHELL to +c:/cygwin/bin/sh. When you invoke a shell in Emacs, this +SHELL is what you get. + + + Set HOME to point to your +home directory. This is where, for example, +bash will look for your .bashrc +file. Ditto emacs looking for .emacsrc + + + + + +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 sh). Notice the hardwired path! +So you need to ensure that your /bin directory has the following +binaries in it: + + sh + perl + cat + +All these come in Cygwin's bin directory, which you probably have +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.) +Provided /bin points to the Cygwin bin +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). + + + + + +Finally, here are some things to be aware of when using Cygwin: + + Cygwin doesn't deal well with filenames that include +spaces. "Program Files" and "Local files" are +common gotchas. + + + Cygwin implements a symbolic link as a text file with some +magical text in it. So other programs that don't use Cygwin's +I/O libraries won't recognise such files as symlinks. +In particular, programs compiled by GHC are meant to be runnable +without having Cygwin, so they don't use the Cygwin library, so +they don't recognise symlinks. + + + +Win32 has a find command which is not the same as Cygwin's find. +You will probably discover that the Win32 find appears in your PATH +before the Cygwin one, because it's in the system PATH +environment variable, whereas you have probably modified the user PATH +variable. You can always invoke find with an absolute path, or rename it. + + + + + + +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 install + +You have to install the following other things to build GHC: + + + +Install an executable GHC, from http://www.haskell.org/ghc. +This is what you will use to compile GHC. Add it in your +PATH: the installer tells you the path element +you need to add upon completion. + + + + + +Install an executable Happy, from http://www.haskell.org/happy. +Happy is a parser generator used to compile the Haskell grammar. Add it in your +PATH. + + + + 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. +Do not add any of the mingw binaries to your path. +They are only going to get used by explicit access (via the --with-gcc flag you +give to configure later). If you do add them to your path +you are likely to get into a mess because their names overlap with Cygwin binaries. + + + +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 (). + + + + + + +Building GHC + +OK! +Now go read the documentation above on building from source (); +the bullets below only tell +you about Windows-specific wrinkles. + -Install a version of GHC, and put it in your -PATH (the installer tells you the path element -you need to add upon completion.) +Run autoconf both in fptools +and in fptools/ghc. If you omit the latter step you'll +get an error when you run ./configure: + +...lots of stuff... +creating mk/config.h +mk/config.h is unchanged +configuring in ghc +running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. +./configure: ./configure: No such file or directory +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), +you get + +/usr/bin/autoconf: cannot create configure: permission denied + +Solution: delete configure first. + + + + +You either need to add ghc to your +PATH before you invoke +configure, or use the configure +option . + + + + +If you are paranoid, delete config.cache if it exists. +This file occasionally remembers out-of-date configuration information, which +can be really confusing. + + + + + + After autoconf run ./configure in + fptools/ thus: + + + ./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 ). + + 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 () +you'll have to do something more like: + + ./configure --with-gcc=...the Cygwin gcc... + + + + + 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. + + +