X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.xml;h=18d3ff4f7941786e3738ab398b685833556cc087;hb=22501a5d518c093b1233af3e5c52503d5aa43281;hp=0375c38d0ba26127405c382138fdba1fb89f4bc3;hpb=97850bacd6441d9459df0ff105434830f6451d62;p=ghc-hetmet.git diff --git a/docs/building/building.xml b/docs/building/building.xml index 0375c38..18d3ff4 100644 --- a/docs/building/building.xml +++ b/docs/building/building.xml @@ -1,27 +1,23 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +]>
-Building the Glasgow Functional Programming Tools Suite +Building and developing GHC The GHC Team
glasgow-haskell-{users,bugs}@haskell.org
- The Glasgow fptools suite is a collection of Functional - Programming related tools, including the Glasgow Haskell - Compiler (GHC). The source code for the whole suite is kept in - a single CVS repository and shares a common build and - installation system. - - This guide is intended for people who want to build or - modify programs from the Glasgow fptools - suite (as distinct from those who merely want to - run them). Installation instructions are - now provided in the user guide. + This Guide is primarily aimed at those who want to build and/or + hack on GHC. It describes how to get started with building GHC on your + machine, and how to tweak the settings to get the kind of build you + want. It also describes the inner workings of the build system, so you + can extend it, modify it, and use it to build your code. The bulk of this guide applies to building on Unix systems; see for Windows notes. @@ -33,8 +29,7 @@ Getting the sources - You can get your hands on the fptools - in two ways: + You can get your hands on the GHC sources in two ways: @@ -49,8 +44,7 @@ (c) you want to hack on GHC yourself. A source distribution contains complete sources for - one or more projects in the fptools - suite. Not only that, but the more awkward + GHC. Not only that, but the more awkward machine-independent steps are done for you. For example, if you don't have happyhappy @@ -65,786 +59,25 @@ - The CVS repository.CVS repository + The darcs repository.darcs repository We make releases infrequently. If you want more up-to-the minute (but less tested) source code then you need - to get access to our CVS repository. + to get access to our darcs repository. - All the fptools source code is held - in a CVS repository. CVS is a pretty good source-code - control system, and best of all it works over the - network. + Information on accessing the darcs repository is on + the wiki: . The repository holds source code only. It holds no mechanically generated files at all. So if you check out a - source tree from CVS you will need to install every utility + source tree from darcs you will need to install every utility so that you can build all the derived files from scratch. - - More information about our CVS repository can be found - in . - - If you are going to do any building from sources (either - from a source distribution or the CVS repository) then you need to - read all of this manual in detail. - - - - Using the CVS repository - - We use CVS (Concurrent Version System) to keep track of our - sources for various software projects. CVS lets several people - work on the same software at the same time, allowing changes to be - checked in incrementally. - - This section is a set of guidelines for how to use our CVS - repository, and will probably evolve in time. The main thing to - remember is that most mistakes can be undone, but if there's - anything you're not sure about feel free to bug the local CVS - meister (namely Jeff Lewis - jlewis@galois.com). - - - Getting access to the CVS Repository - - You can access the repository in one of two ways: - read-only (), or read-write (). - - - Remote Read-only CVS Access - - Read-only access is available to anyone - there's no - need to ask us first. With read-only CVS access you can do - anything except commit changes to the repository. You can - make changes to your local tree, and still use CVS's merge - facility to keep your tree up to date, and you can generate - patches using 'cvs diff' in order to send to us for - inclusion. - - To get read-only access to the repository: - - - - Make sure that cvs is - installed on your machine. - - - Set your $CVSROOT environment variable to - :pserver:anoncvs@cvs.haskell.org:/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 -$ cvs login - The password is simply cvs. This - sets up a file in your home directory called - .cvspass, which squirrels away the - dummy password, so you only need to do this step once. - - - - Now go to . - - - - - - Remote Read-Write CVS Access - - We generally supply read-write access to folk doing - serious development on some part of the source tree, when - going through us would be a pain. If you're developing some - feature, or think you have the time and inclination to fix - bugs in our sources, feel free to ask for read-write - access. There is a certain amount of responsibility that goes - with commit privileges; we are more likely to grant you access - if you've demonstrated your competence by sending us patches - via mail in the past. - - To get remote read-write CVS access, you need to do the - following steps. - - - - Make sure that cvs and - ssh are both installed on your - machine. - - - - Generate a DSA private-key/public-key pair, thus: -$ ssh-keygen -d - (ssh-keygen comes with - ssh.) Running ssh-keygen - -d creates the private and public keys in - $HOME/.ssh/id_dsa and - $HOME/.ssh/id_dsa.pub respectively - (assuming you accept the standard defaults). - - ssh-keygen -d will only work if - you have Version 2 ssh installed; it - will fail harmlessly otherwise. If you only have Version - 1 you can instead generate an RSA key pair using plain -$ ssh-keygen - - Doing so creates the private and public RSA keys in - $HOME/.ssh/identity and - $HOME/.ssh/identity.pub - respectively. - - [Deprecated.] Incidentally, you can force a Version - 2 ssh to use the Version 1 protocol by - creating $HOME/config with the - following in it: -BatchMode Yes - -Host cvs.haskell.org -Protocol 1 - - In both cases, ssh-keygen will - ask for a passphrase. The - passphrase is a password that protects your private key. - In response to the 'Enter passphrase' question, you can - either: - - - [Recommended.] Enter a passphrase, which you - will quote each time you use CVS. - ssh-agent makes this entirely - un-tiresome. - - - [Deprecated.] Just hit return (i.e. use an empty - passphrase); then you won't need to quote the - passphrase when using CVS. The downside is that - anyone who can see into your .ssh - directory, and thereby get your private key, can mess - up the repository. So you must keep the - .ssh directory with draconian - no-access permissions. - - - - - - Windows users: see the notes in about ssh wrinkles! - - - - - - - Send a message to to the CVS repository - administrator (currently Jeff Lewis - jeff@galois.com), containing: - - - Your desired user-name. - - - Your .ssh/id_dsa.pub (or - .ssh/identity.pub). - - - He will set up your account. - - - - Set the following environment variables: - - - - $HOME: points to your home directory. This is where CVS - will look for its .cvsrc file. - - - - - - $CVS_RSH to ssh - - [Windows users.] Setting your CVS_RSH to - ssh assumes that your CVS client - understands how to execute shell script - ("#!"s,really), which is what - ssh is. This may not be the case on - Win32 platforms, so in that case set CVS_RSH to - ssh1. - - - - $CVSROOT to - :ext:your-username - @cvs.haskell.org:/home/cvs/root - where your-username is your user name on - cvs.haskell.org. - - The CVSROOT environment variable will - be recorded in the checked-out tree, so you don't need to set - this every time. - - - - - - $CVSEDITOR: bin/gnuclient.exe - if you want to use an Emacs buffer for typing in those long commit messages. - - - - - - $SHELL: To use bash as the shell in Emacs, you need to - set this to point to bash.exe. - - - - - - - - - - - Put the following in $HOME/.cvsrc: - - -checkout -P -release -d -update -P -diff -u - - - These are the default options for the specified CVS commands, - and represent better defaults than the usual ones. (Feel - free to change them.) - - - - [Windows users.] Filenames starting with . were illegal in - the 8.3 DOS filesystem, but that restriction should have - been lifted by now (i.e., you're using VFAT or later filesystems.) If - you're still having problems creating it, don't worry; .cvsrc is entirely - optional. - - - - - - - [Experts.] Once your account is set up, you can get - access from other machines without bothering Jeff, thus: - - - Generate a public/private key pair on the new - machine. - - - Use ssh to log in to - cvs.haskell.org, from your old - machine. - - - Add the public key for the new machine to the file - $HOME/ssh/authorized_keys on - cvs.haskell.org. - (authorized_keys2, I think, for Version - 2 protocol.) - - - Make sure that the new version of - authorized_keys still has 600 file - permissions. - - - - - - - - - Checking Out a Source Tree - - - - Make sure you set your CVSROOT - environment variable according to either of the remote - methods above. The Approved Way to check out a source tree - is as follows: - -$ cvs checkout fpconfig - - At this point you have a new directory called - fptools which contains the basic stuff - for the fptools suite, including the configuration files and - some other junk. - -[Windows users.] The following messages appear to be harmless: -setsockopt IPTOS_LOWDELAY: Invalid argument -setsockopt IPTOS_THROUGHPUT: Invalid argument - - - - You can call the fptools directory whatever you like, - CVS won't mind: - -$ mv fptools directory - - NB: after you've read the CVS manual you might be - tempted to try -$ cvs checkout -d directory fpconfig - - instead of checking out fpconfig - and then renaming it. But this doesn't work, and will - result in checking out the entire repository instead of just - the fpconfig bit. -$ cd directory -$ cvs checkout ghc 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 libraries - modules (for a full list of the projects available, see - ). - - Remember that if you do not have - happy and/or Alex - installed, you need to check them out as well. - - - - - - Committing Changes - - This is only if you have read-write access to the - repository. For anoncvs users, CVS will issue a "read-only - repository" error if you try to commit changes. - - - - Build the software, if necessary. Unless you're just - working on documentation, you'll probably want to build the - software in order to test any changes you make. - - - - Make changes. Preferably small ones first. - - - - Test them. You can see exactly what changes you've - made by using the cvs diff command: -$ cvs diff - lists all the changes (using the - diff command) in and below the current - directory. In emacs, C-c C-v = runs - cvs diff on the current buffer and shows - 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: - -$ cd fptools -$ cvs update - This pulls in any changes that other people have made, - and merges them with yours. If there are any conflicts, CVS - will tell you, and you'll have to resolve them before you - can check your changes in. The documentation describes what - to do in the event of a conflict. - - It's not always necessary to do a full cvs update - before checking in a change, since CVS will always tell you - if you try to check in a file that someone else has changed. - However, you should still update at regular intervals to - avoid making changes that don't work in conjuction with - changes that someone else made. Keeping an eye on what goes - by on the mailing list can help here. - - - - When you're happy that your change isn't going to - break anything, check it in. For a one-file change: - -$ cvs commit filename - - CVS will then pop up an editor for you to enter a - "commit message", this is just a short description - of what your change does, and will be kept in the history of - the file. - - If you're using emacs, simply load up the file into a - buffer and type C-x C-q, and emacs will - prompt for a commit message and then check in the file for - you. - - For a multiple-file change, things are a bit - trickier. There are several ways to do this, but this is the - way I find easiest. First type the commit message into a - temporary file. Then either - -$ cvs commit -F commit-message file_1 .... file_n - - or, if nothing else has changed in this part of the - source tree, - -$ cvs commit -F commit-message directory - - where directory is a common - parent directory for all your changes, and - commit-message is the name of the - file containing the commit message. - - Shortly afterwards, you'll get some mail from the - relevant mailing list saying which files changed, and giving - the commit message. For a multiple-file change, you should - still get only one message. - - - - - - Updating Your Source Tree - - It can be tempting to cvs update just part of a source - tree to bring in some changes that someone else has made, or - before committing your own changes. This is NOT RECOMMENDED! - Quite often changes in one part of the tree are dependent on - changes in another part of the tree (the - mk/*.mk files are a good example where - problems crop up quite often). Having an inconsistent tree is a - major cause of headaches. - - So, to avoid a lot of hassle, follow this recipe for - updating your tree: - -$ cd fptools -$ cvs update -P 2>&1 | tee log - - Look at the log file, and fix any conflicts (denoted by a - 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 -$ lndir source-tree - - Some files might have been removed, so you need to remove - the links pointing to these non-existent files: - -$ find . -xtype l -exec rm '{}' \; - - To be really safe, you should do - - -$ gmake all - - from the top-level, to update the dependencies and build - any changed files. - - - - GHC Tag Policy - - If you want to check out a particular version of GHC, - you'll need to know how we tag versions in the repository. The - policy (as of 4.04) is: - - - - The tree is branched before every major release. The - branch tag is ghc-x-xx-branch, where - x-xx is the version number of the release - with the '.' replaced by a - '-'. For example, the 4.04 release lives - on ghc-4-04-branch. - - - - The release itself is tagged with - ghc-x-xx (on the branch). eg. 4.06 is - called ghc-4-06. - - - - We didn't always follow these guidelines, so to see - what tags there are for previous versions, do cvs - log on a file that's been around for a while (like - fptools/ghc/README). - - - - So, to check out a fresh GHC 4.06 tree you would - do: - -$ cvs co -r ghc-4-06 fpconfig -$ cd fptools -$ cvs co -r ghc-4-06 ghc libraries - - - - General Hints - - - - As a general rule: commit changes in small units, - preferably addressing one issue or implementing a single - feature. Provide a descriptive log message so that the - repository records exactly which changes were required to - implement a given feature/fix a bug. I've found this - very useful in the past for finding out - when a particular bug was introduced: you can just wind back - the CVS tree until the bug disappears. - - - - Keep the sources at least *buildable* at any given - time. No doubt bugs will creep in, but it's quite easy to - ensure that any change made at least leaves the tree in a - buildable state. We do nightly builds of GHC to keep an eye - on what things work/don't work each day and how we're doing - in relation to previous verions. This idea is truely wrecked - if the compiler won't build in the first place! - - - - To check out extra bits into an already-checked-out - tree, use the following procedure. Suppose you have a - checked-out fptools tree containing just ghc, and you want - to add nofib to it: - -$ cd fptools -$ cvs checkout nofib - - or: - -$ cd fptools -$ cvs update -d nofib - - (the -d flag tells update to create a new - directory). If you just want part of the nofib suite, you - can do - -$ cd fptools -$ cvs checkout nofib/spectral - - This works because nofib is a - module in its own right, and spectral is a subdirectory of - the nofib module. The path argument to checkout must always - start with a module name. There's no equivalent form of this - command using update. - - - - - - - What projects are there? - - The fptools suite consists of several - projects, most of which can be downloaded, - built and installed individually. Each project corresponds to a - subdirectory in the source tree, and if checking out from CVS then - each project can be checked out individually by sitting in the top - level of your source tree and typing cvs checkout - project. - - Here is a list of the projects currently available: - - - - - alex - alexproject - - - The Alex lexical - analyser generator for Haskell. - - - - - - ghc - ghc - project - - - The Glasgow - Haskell Compiler (minus libraries). Absolutely - required for building GHC. - - - - - - glafp-utils - glafp-utilsproject - - - Utility programs, some of which are used by the - build/installation system. Required for pretty much - everything. - - - - - - greencard - greencardproject - - - The GreenCard - system for generating Haskell foreign function - interfaces. - - - - - - haggis - haggisproject - - - The Haggis - Haskell GUI framework. - - - - - - haddock - haddockproject - - - The Haddock - documentation tool. - - - - - - happy - happyproject - - - The Happy Parser - generator. - - - - - - hdirect - hdirectproject - - - The H/Direct - Haskell interoperability tool. - - - - - - hood - hoodproject - - - The Haskell - Object Observation Debugger. - - - - - - hslibs - hslibsproject - - - Old, now deprecated, libraries. Everything in here is in libraries. - - - - - - libraries - project - - - Hierarchical Haskell library suite - (required for building GHC). - - - - - - mhms - project - - - The Modular Haskell Metric System. - - - - - - nofib - nofibproject - - - The NoFib suite: A collection of Haskell programs used - primarily for benchmarking. - - - - - - testsuite - testsuiteproject - - - A testing framework, including GHC's regression test - suite. - - - - - So, to build GHC you need at least the - ghc and libraries - projects (a GHC source distribution will - already include the bits you need). @@ -863,11 +96,12 @@ $ cvs checkout nofib/spectral - Use an appropriate machine / operating system. lists the supported platforms; if - yours isn't amongst these then you can try porting GHC (see - ). - + Use an appropriate machine / operating system. GHC + Platform Support lists the currently supported + platforms; if yours isn't amongst these then you can try + porting GHC (see ). + Be sure that the “pre-supposed” utilities are @@ -902,280 +136,6 @@ $ cvs checkout nofib/spectral - - What machines the Glasgow tools run on - -portsGHC -GHCports -platformssupported - - The main question is whether or not the Haskell compiler - (GHC) runs on your platform. - - A “platform” is a - architecture/manufacturer/operating-system combination, such as - sparc-sun-solaris2. Other common ones are - alpha-dec-osf2, - hppa1.1-hp-hpux9, - i386-unknown-linux, - i386-unknown-solaris2, - i386-unknown-freebsd, - i386-unknown-cygwin32, - m68k-sun-sunos4, - mips-sgi-irix5, - sparc-sun-sunos4, - sparc-sun-solaris2, - powerpc-ibm-aix. - - Some libraries may only work on a limited number of - platforms; for example, a sockets library is of no use unless the - operating system supports the underlying BSDisms. - - - What platforms the Haskell compiler (GHC) runs on - - fully-supported platforms - native-code generator - registerised ports - unregisterised ports - - The GHC hierarchy of Porting Goodness: (a) Best is a - native-code generator; (b) next best is a - “registerised” port; (c) the bare minimum is an - “unregisterised” port. - (“Unregisterised” is so terrible that we won't say - more about it). - - We use Sparcs running Solaris 2.7 and x86 boxes running - FreeBSD and Linux, so those are the best supported platforms, - unsurprisingly. - - Here's everything that's known about GHC ports. We - identify platforms by their “canonical” - CPU/Manufacturer/OS triple. - - - - alpha-dec-{osf,linux,freebsd,openbsd,netbsd}: - alpha-dec-osf - alpha-dec-linux - alpha-dec-freebsd - alpha-dec-openbsd - alpha-dec-netbsd - - - The OSF port is currently working (as of GHC version - 5.02.1) and well supported. The native code generator is - currently non-working. Other operating systems will - require some minor porting. - - - - - sparc-sun-sunos4 - sparc-sun-sunos4 - - - Probably works with minor tweaks, hasn't been tested - for a while. - - - - - sparc-sun-solaris2 - sparc-sun-solaris2 - - - Fully supported (at least for Solaris 2.7 and 2.6), - including native-code generator. - - - - - sparc-unknown-openbsd - sparc-unknown-openbsd - - - Supported, including native-code generator. The - same should also be true of NetBSD - - - - - hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x) - hppa1.1-hp-hpux - - - A registerised port is available for version 4.08, - but GHC hasn't been built on that platform since (as far - as we know). No native-code generator. - - - - - i386-unknown-linux (PCs running Linux, ELF binary format) - i386-*-linux - - - GHC works registerised and has a native code - generator. You must have GCC 2.7.x - or later. NOTE about glibc versions: - GHC binaries built on a system running glibc - 2.0 won't work on a system running - glibc 2.1, and vice versa. In general, - don't expect compatibility between - glibc versions, even if the shared - library version hasn't changed. - - - - - i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher) - i386-unknown-freebsd - - - GHC works registerised. Pre-built packages are - available in the native package format, so if you just - need binaries you're better off just installing the - package (it might even be on your installation - CD!). - - - - - i386-unknown-openbsd (PCs running OpenBSD) - i386-unknown-openbsd - - - Supported, with native code generator. Packages are - available through the ports system in the native package - format. - - - - - i386-unknown-netbsd (PCs running NetBSD) - i386-unknown-netbsd - - - Will require some minor porting effort, but should - work registerised. - - - - - i386-unknown-mingw32 (PCs running Windows) - i386-unknown-mingw32 - - - Fully supported under Win9x, WinNT, Win2k, and - WinXP. Includes a native code generator. Building from - source requires a recent Cygwin distribution - to be installed. - - - - - ia64-unknown-linux - ia64-unknown-linux - - - Supported, except there is no native code - generator. - - - - - x86_64-unknown-linux - x86_64-unknown-linux - - - GHC currently works unregisterised. A registerised - port is in progress. - - - - - amd64-unknown-openbsd - amd64-unknown-linux - - - (This is the same as x86_64-unknown-openbsd). GHC - currently works unregisterised. A registerised port is in - progress. - - - - - mips-sgi-irix5 - mips-sgi-irix[5-6] - - - Port has worked in the past, but hasn't been tested - for some time (and will certainly have rotted in various - ways). As usual, we don't have access to machines and - there hasn't been an overwhelming demand for this port, - but feel free to get in touch. - - - - - mips64-sgi-irix6 - mips-sgi-irix6 - - - GHC currently works unregisterised. - - - - - powerpc-ibm-aix - powerpc-ibm-aix - - - Port currently doesn't work, needs some minimal - porting effort. As usual, we don't have access to - machines and there hasn't been an overwhelming demand for - this port, but feel free to get in touch. - - - - - powerpc-apple-darwin - powerpc-apple-darwin - - - Supported registerised. Native code generator is - almost working. - - - - - powerpc-apple-linux - powerpc-apple-linux - - - Not supported (yet). - - - - - Various other systems have had GHC ported to them in the - distant past, including various Motorola 68k boxes. The 68k - support still remains, but porting to one of these systems will - certainly be a non-trivial task. - - - - What machines the other tools run on - - Unless you hear otherwise, the other tools work if GHC - works. - - - - Installing pre-supposed utilities @@ -1198,10 +158,12 @@ $ cvs checkout nofib/spectral 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 . + GHC is required to build GHC, because GHC itself is + written in Haskell, and uses GHC extensions. It is possible + to build GHC using just a C compiler, and indeed some + distributions of GHC do just that, but it isn't the best + supported method, and you may encounter difficulties. Full + instructions are in . Which version of GHC you need will depend on the packages you intend to build. GHC itself will normally @@ -1242,16 +204,12 @@ $ cvs checkout nofib/spectral GCC (GNU C compiler), pre-supposed - We recommend using GCC version 2.95.2 on all - platforms. Failing that, version 2.7.2 is stable on most - platforms. Earlier versions of GCC can be assumed not to - work, and versions in between 2.7.2 and 2.95.2 (including - 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. - + Most GCC versions should work with the most recent GHC + sources. Expect trouble if you use a recent GCC with + an older GHC, though (trouble in the form of mis-compiled code, + link errors, and errors from the ghc-asm + script). + 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 x86 @@ -1266,28 +224,33 @@ $ cvs checkout nofib/spectral makeGNU - The fptools build system makes heavy use of features + The GHC build system makes heavy use of features specific to GNU make, so you must have - this installed in order to build any of the fptools - suite. + this installed in order to build GHC. + + NB. it has been reported that version 3.79 no longer + works to build GHC, and 3.80 is required. - Happy + Happy Happy Happy is a parser generator tool for Haskell, and is - used to generate GHC's parsers. Happy is written in - Haskell, and is a project in the CVS repository - (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 distribution of either Happy or GHC to get - started. Happy distributions are available from Happy's Web - Page. + used to generate GHC's parsers. + + If you start from a source tarball of GHC (i.e. not a darcs + checkout), then you don't need Happy, because we supply the + pre-processed versions of the Happy parsers. If you intend to + modify the compiler and/or you're using a darcs checkout, then you + need Happy. + + Happy version 1.15 is currently required to build GHC. + Grab a copy from Happy's Web + Page. @@ -1297,10 +260,15 @@ $ cvs checkout nofib/spectral Alex is a lexical-analyser generator for Haskell, - which GHC uses to generate its lexer. Like Happy, Alex is - written in Haskell and is a project in the CVS repository. - Alex distributions are available from Alex's Web + which GHC uses to generate its lexer. + + Like Happy, you don't need Alex if you're building GHC from a + source tarball, but you do need it if you're modifying GHC and/or + building a darcs checkout. + + Alex is + written in Haskell and is a project in the darcs repository. + Alex distributions are available from Alex's Web Page. @@ -1312,7 +280,7 @@ $ cvs checkout nofib/spectral GNU autoconf is needed if you intend to build from the - CVS sources, it is not needed if you + darcs sources, it is not needed if you just intend to build a standard source distribution. Version 2.52 or later of the autoconf package is required. @@ -1344,13 +312,6 @@ $ cvs checkout nofib/spectral - One fptools project is worth a quick note - at this point, because it is useful for all the others: - glafp-utils contains several utilities which - aren't particularly Glasgow-ish, but Occasionally Indispensable. - Like lndir for creating symbolic link - trees. - Tools for building parallel GHC (GPH) @@ -1392,29 +353,9 @@ $ cvs checkout nofib/spectral - - - - Other useful tools - - - - Flex - pre-supposed: flex - flex, pre-supposed - - - This is a quite-a-bit-better-than-Lex lexer. Used - to build a couple of utilities in - glafp-utils. Depending on your - operating system, the supplied lex may - or may not work; you should get the GNU version. - - - - More tools are required if you want to format the documentation - that comes with GHC and other fptools projects. See More tools are required if you want to format the + documentation that comes with GHC. See . @@ -1425,89 +366,77 @@ $ cvs checkout nofib/spectral Building from source Source, building from - You've been rash enough to want to build some of the Glasgow - Functional Programming tools (GHC, Happy, nofib, etc.) from - source. You've slurped the source, from the CVS repository or - from a source distribution, and now you're sitting looking at a - huge mound of bits, wondering what to do next. - - Gingerly, you type make. Wrong - already! - - This rest of this guide is intended for duffers like me, who - aren't really interested in Makefiles and systems configurations, - but who need a mental model of the interlocking pieces so that - they can make them work, extend them consistently when adding new - software, and lay hands on them gently when they don't - work. - - - Quick Start + “I just want to build it!” - If you are starting from a source distribution, and just - want a completely standard build, then the following procedure should - work (unless you're on Windows, in which case go to ). + No problem. This recipe should build and install a working GHC with + all the default settings. (unless you're + on Windows, in which case go to ). -$ autoreconf +$ autoreconfnot necessary if you started from a source tarball + $ ./configure $ make $ make install For GHC, this will do a 2-stage bootstrap build of the compiler, with profiling libraries, and install the - results. + results in the default location (under /usr/local on + Unix, for example). + + The configure script is a standard GNU + autoconf script, and accepts the usual options for + changing install locations and the like. Run + ./configure --help for a list of options. If you want to do anything at all non-standard, or you want to do some development, read on... - - - - Your source tree - - The source code is held in your source - tree. The root directory of your source tree - must contain the following directories and - files: - - - - Makefile: the root - Makefile. - - - - mk/: the directory that contains - the main Makefile code, shared by all the - fptools software. - - - - configure.ac, - config.sub, - config.guess: these files support the - configuration process. - - - - install-sh. - - + + + + Quick start for GHC developers + + This section is a copy of the file + HACKING from the GHC source tree. It describes + how to get started with setting up your build tree for developing GHC + or its libraries, and how to start building. + + +&hacking; + + + + + Working with the build system + + This rest of this guide is intended for duffers like me, who + aren't really interested in Makefiles and systems configurations, + but who need a mental model of the interlocking pieces so that + they can make them work, extend them consistently when adding new + software, and lay hands on them gently when they don't + work. - All the other directories are individual - projects of the fptools - system—for example, the Glasgow Haskell Compiler - (ghc), the Happy parser generator - (happy), the nofib - benchmark suite, and so on. You can have zero or more of these. - Needless to say, some of them are needed to build others. - - The important thing to remember is that even if you want - only one project (happy, say), you must have - a source tree whose root directory contains - Makefile, mk/, - configure.ac, and the project(s) you want - (happy/ in this case). You cannot get by - with just the happy/ directory. + + History + + First, a historical note. The GHC build system used to be + called "fptools": a generic build system used to build multiple + projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a + concept of the generic project-independent parts, and + project-specific parts that resided in a project + subdirectory. + + Nowadays, most of these other projects are using Cabal, or have faded + away, and GHC is the only regular user of the fptools build + system. We decided therefore to simplify the situation for + developers, and specialise the build system for GHC. This + resulted in a simpler organisation of the source tree and the + build system, which hopefully makes the whole thing easier to + understand. + + You might find old comments that refer to "projects" or + "fptools" in the documentation and/or source; please let us know + if you do. @@ -1536,7 +465,7 @@ $ make install are two (If you don't have either, the source distribution includes sources for the X11 lndir—check out - fptools/glafp-utils/lndir). See utils/lndir). See for a typical invocation. The build tree does not need to be anywhere near the @@ -1573,24 +502,23 @@ $ make install source file.) Like the source tree, the top level of your build tree - must be (a linked copy of) the root directory of the - fptools suite. Inside Makefiles, the root of - your build tree is called + must be (a linked copy of) the root directory of the GHC source + tree.. Inside Makefiles, the root of your build tree is called $(FPTOOLS_TOP)FPTOOLS_TOP. In the rest of this document path names are relative to $(FPTOOLS_TOP) unless otherwise stated. For example, the file - ghc/mk/target.mk is actually - $(FPTOOLS_TOP)/ghc/mk/target.mk. + mk/target.mk is actually + $(FPTOOLS_TOP)/mk/target.mk. Getting the build you want - When you build fptools you will be - compiling code on a particular host - platform, to run on a particular target - platform (usually the same as the host + When you build GHC you will be compiling code on a + particular host platform, to run on a + particular target platform (usually the + same as the host platform)platform. The difficulty is that there are minor differences between different platforms; minor, but enough that the code needs to be @@ -1599,12 +527,11 @@ $ make install different native-code generator. There are also knobs you can turn to control how the - fptools software is built. For example, you - might want to build GHC optimised (so that it runs fast) or - unoptimised (so that you can compile it fast after you've - modified it. Or, you might want to compile it with debugging on - (so that extra consistency-checking code gets included) or off. - And so on. + software is built. For example, you might want to build GHC + optimised (so that it runs fast) or unoptimised (so that you can + compile it fast after you've modified it. Or, you might want to + compile it with debugging on (so that extra consistency-checking + code gets included) or off. And so on. All of this stuff is called the configuration of your build. You set the @@ -1615,7 +542,7 @@ $ make install Step 1: get ready for configuration. NOTE: if you're starting from a source distribution, - rather than CVS sources, you can skip this step. + rather than darcs sources, you can skip this step. Change directory to $(FPTOOLS_TOP) and @@ -1633,7 +560,8 @@ $ make install a message like "No rule to make target 'mk/config.h.in'". - Some projects, including GHC, have their own configure script. + Some parts of the source tree, particularly + libraries, 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). @@ -1726,7 +654,10 @@ $ make install Specifies the path to any installed Haskell compiler. This compiler will be used for compiling generic Haskell code. The default is to use - ghc. + ghc. (NOTE: I'm not sure it + actually works to specify a compiler other than GHC + here; unless you really know what you're doing I + suggest not using this option at all.) @@ -1751,7 +682,7 @@ $ make install Step 3: build configuration. Next, you say how this build of - fptools is to differ from the standard + GHC is to differ from the standard defaults by creating a new file mk/build.mkbuild.mk in the build tree. This file is the @@ -1788,13 +719,14 @@ $ make install 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 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: -GhcHcOpts=-O -Rghc-timing +GhcHcOpts=-Rghc-timing The accompanying comment explains that this is the list of flags passed to GHC when building GHC itself. For doing @@ -1802,20 +734,30 @@ $ make install enable debugging code. So you would add the following to build.mk: - or, if you prefer, - GhcHcOpts += -DDEBUG GNU make allows existing definitions to have new text appended using the “+=” - operator, which is quite a convenient feature.) + operator, which is quite a convenient feature. + + Haskell compilations by default have -O + turned on, by virtue of this setting from + config.mk: - If you want to remove the -O as well (a - good idea when developing, because the turn-around cycle gets a - lot quicker), you can just override - GhcLibHcOpts altogether: +SRC_HC_OPTS += -H16m -O -GhcHcOpts=-DDEBUG -Rghc-timing + SRC_HC_OPTS means "options for HC from + the source tree", where HC stands for Haskell Compiler. + SRC_HC_OPTS are added to every Haskell + compilation. To turn off optimisation, you could add this to + build.mk: + +SRC_HC_OPTS = -H16m -O0 + + Or you could just add -O0 to + GhcHcOpts to turn off optimisation for the + compiler. See for some more + suggestions. When reading config.mk.in, remember that anything between “@...@” signs is going to be substituted @@ -1848,7 +790,6 @@ $ make install correct directory is hard to find automatically. If you find that configure has got it wrong, just put the correct definition in build.mk. - @@ -1859,21 +800,18 @@ $ make install - Get your source tree from somewhere (CVS repository + Get your source tree from somewhere (darcs repository or source distribution). Say you call the root directory - myfptools (it does not have to be - called fptools). Make sure that you - have the essential files (see ). + myghc (it does not have to be + called ghc). - (Optional) Use lndir or mkshadowdir to create a build tree. -$ cd myfptools -$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 +$ cd myghc +$ mkshadowdir . /scratch/joe-bloggs/myghc-x86 (N.B. mkshadowdir's first argument is taken relative to its second.) You probably want to give @@ -1886,7 +824,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Change directory to the build tree. Everything is going to happen there now. -$ cd /scratch/joe-bloggs/myfptools-sun4 +$ cd /scratch/joe-bloggs/myghc-x86 @@ -1916,8 +854,6 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Create the file mk/build.mk, adding definitions for your desired configuration options. - -$ emacs mk/build.mk @@ -1925,10 +861,9 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 mk/build.mk as often as you like. You do not have to run any further configuration programs to make these changes take effect. In theory you should, however, say - gmake clean, gmake all, - because configuration option changes could affect - anything—but in practice you are likely to know what's - affected. + make clean; make, because configuration + option changes could affect anything—but in practice you + are likely to know what's affected. @@ -1939,18 +874,23 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 things. The first thing you need to know is that you - must use GNU make, usually called - gmake, not standard Unix - make. If you use standard Unix - make you will get all sorts of error messages - (but no damage) because the fptools + must use GNU make. On some + systems this is called gmake, whereas on + others it is the standard make command. In + this document we will always refer to it as + make; please substitute with + gmake if your system requires it. If you use + a the wrong make you will get all sorts of + error messages (but no damage) because the GHC Makefiles use GNU make's facilities extensively. To just build the whole thing, cd to - the top of your fptools tree and type - gmake. This will prepare the tree and build - the various projects in the correct order. + the top of your build tree and type make. + This will prepare the tree and build the various parts in the + correct order, resulting in a complete build of GHC that can + even be used directly from the tree, without being installed + first. @@ -1967,13 +907,12 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 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: + by the top-level Makefile, so if you want + everything to work automatically it's best to start + make from the top of the tree. The top-level + Makefile is set up to do a 2-stage + bootstrap by default (when you say make). + Some other targets it supports are: @@ -2029,14 +968,14 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 The stage1, stage2 and stage3 targets also work in the - ghc/compiler directory, but don't forget that + 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. + compiler. @@ -2051,7 +990,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 boot does the one-off preparation required to get ready - for the real work. Notably, it does gmake + for the real work. Notably, it does make depend in all directories that contain programs. It also builds the necessary tools for compilation to proceed. @@ -2059,14 +998,14 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Invoking the boot target explicitly is not normally necessary. From the top-level fptools directory, invoking - gmake causes gmake boot + make causes make boot all to be invoked in each of the project subdirectories, in the order specified by $(AllTargets) in config.mk. If you're working in a subdirectory somewhere and - need to update the dependencies, gmake + need to update the dependencies, make boot is a good way to do it. @@ -2078,8 +1017,8 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Depending on which directory you are in a “final target” may be an executable program, a library archive, a shell script, or a Postscript file. Typing - gmake alone is generally the same as - typing gmake all. + make alone is generally the same as + typing make all. @@ -2120,7 +1059,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Delete all files from the current directory that are normally created by building the program. Don't delete the files that record the configuration, or files - generated by gmake boot. Also preserve + generated by make boot. Also preserve files that could be made by building, but normally aren't because the distribution comes with them. @@ -2243,11 +1182,11 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 If you want to build GHC (say) and just use it direct from the build tree without doing make install first, you can run the in-place driver script: - ghc/compiler/ghc-inplace. + compiler/ghc-inplace. Do NOT use - ghc/compiler/ghc, or - ghc/compiler/ghc-6.xx, as these are the + compiler/ghc, or + 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. @@ -2270,7 +1209,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 make is going to rebuild everything anyway, the following hack may be useful: -$ gmake FAST=YES +$ make FAST=YES This tells the make system to ignore dependencies and just build what you tell it to. In other words, it's equivalent to @@ -2292,7 +1231,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 makefile architecture make is great if everything - works—you type gmake install and lo! the + works—you type make install and lo! the right things get compiled and installed in the right places. Our goal is to make this happen often, but somehow it often doesn't; instead some weird error message eventually emerges from the @@ -2390,7 +1329,7 @@ directive. include other files. (Unfortunately, when an included file does an include, the filename is treated relative - to the directory in which gmake is being + to the directory in which make is being run, not the directory in which the included sits.) In general, every file foo.mk assumes @@ -2439,7 +1378,7 @@ directive. The last section includes a second file of standard code, called target.mktarget.mk. - It contains the rules that tell gmake how + It contains the rules that tell make how to make the standard targets (). Why, you ask, can't this standard code be part of @@ -2461,12 +1400,12 @@ directive. In our example Makefile, most of the work is done by the two included files. When - you say gmake all, the following things + you say make all, the following things happen: - gmake figures out that the object + make figures out that the object files are Foo.o and Baz.o. @@ -2490,7 +1429,7 @@ directive. compiler to do the link step. (Why not use ld? Because the Haskell compiler knows what standard libraries to link in. How did - gmake know to use the Haskell compiler to + make know to use the Haskell compiler to do the link, rather than the C compiler? Because we set the variable HS_PROG rather than C_PROG.) @@ -2535,7 +1474,7 @@ directive. Makefile in $(FPTOOLS_TOP)/ghc. It does most of its work by recursively invoking - gmake on the Makefiles + make on the Makefiles in the sub-directories. We say that ghc/Makefile is a non-leaf Makefile, because it does little @@ -2617,7 +1556,7 @@ directive. Standard pattern rules that - tell gmake how to construct one file + tell make how to construct one file from another. @@ -2627,7 +1566,7 @@ directive. of each Makefile, so that the user can replace the boilerplate definitions or pattern rules by simply giving a new definition or pattern rule in the - Makefile. gmake + Makefile. make simply takes the last definition as the definitive one. Instead of replacing boilerplate @@ -2660,7 +1599,7 @@ directive. - gmake commits target and + make commits target and dependency lists earlier than it should. For example, target.mk has a rule that looks like this: @@ -2674,8 +1613,8 @@ directive. and $(OBJS)OBJS would not have their final values at the moment - gmake encountered the rule. Alas, - gmake takes a snapshot of their + make encountered the rule. Alas, + make takes a snapshot of their current values, and wires that snapshot into the rule. (In contrast, the commands executed when the rule “fires” are only substituted at the moment @@ -3097,7 +2036,7 @@ directive. extra options to pass to all C compilations. This is intended for command line use, thus: -$ gmake libHS.a EXTRA_CC_OPTS="-v" +$ make libHS.a EXTRA_CC_OPTS="-v" @@ -3212,7 +2151,7 @@ directive. dependencies say to do so. This means that you can, for example, define both HS_PROG and LIBRARY, which will generate two rules for - install. When you type gmake + install. When you type make install both rules will be fired, and both the program and the library will be installed, just as you wanted. @@ -3242,7 +2181,7 @@ directive. These recursive invocations are guaranteed to occur in the order in which the list of directories is specified in SUBDIRS. This guarantee can - be important. For example, when you say gmake + be important. For example, when you say make boot it can be important that the recursive invocation of make boot is done in one sub-directory (the include files, say) before another (the source files). @@ -3288,11 +2227,11 @@ directive. A make variable called way holds the current way tag. way is only ever set on the - command line of gmake (usually in - a recursive invocation of gmake by the + command line of make (usually in + a recursive invocation of make by the system). It is never set inside a Makefile. So it is a global constant for - any one invocation of gmake. Two other + any one invocation of make. Two other make variables, way_ and _way are immediately derived from @@ -3337,9 +2276,9 @@ directive. Foo.mp_o) there is a rule which recursively invokes make to make the specified target, setting the way - variable. So if you say gmake + variable. So if you say make Foo.mp_o you should see a recursive - invocation gmake Foo.mp_o way=mp, + invocation make Foo.mp_o way=mp, and in this recursive invocation the pattern rule for compiling a Haskell file into a .o file will match. The key pattern rules (in @@ -3791,7 +2730,8 @@ GhcBootLibs = YES change TARGETPLATFORM appropriately, and set the variables involving - TARGET to the correct values for + TARGET or + Target to the correct values for the target platform. This step is necessary because currently configure doesn't cope with specifying different values for the @@ -3853,11 +2793,10 @@ $ make boot stage=2 && make stage=2 -$ cd H/ghc/lib/compat +$ cd H/compat $ make clean $ rm .depend -$ make boot UseStage1=YES -$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' +$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' $ cd H/ghc/utils $ make clean $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' @@ -4182,7 +3121,7 @@ above. -and try again: gmake. (see for information about +and try again: make. (see for information about <module>_HC_OPTS.) Alternatively, just cut to the chase: @@ -4287,7 +3226,7 @@ Posix interface. 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. +ls, nor build-system stuff such as make and darcs. For that, there are two choices: Cygwin and MSYS: @@ -4310,7 +3249,7 @@ 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 +darcs, 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, @@ -4509,7 +3448,7 @@ download the following (of course, the version numbers will differ): The MSYS developer's toolkit (binary is sufficient): msysDTK-1.0.1.exe. This provides make, autoconf, - ssh, cvs and probably more besides. + ssh and probably more besides. Run both executables (in the order given above) to install them. I put them in c:/msys @@ -4860,8 +3799,7 @@ 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 (). - +the darcs repository, following the instructions at . @@ -5002,18 +3940,16 @@ choices, but it gives a single path that works. - add C:\ghc\ghc-6.4.1\bin to %PATH% (Start->Control Panel->System->Advanced->Environment Variables) -- Get cvs version of ghc +- Get darcs version of ghc ; also, subscribe to cvs-all@haskell.org, or follow the mailing list ; archive, in case you checkout a version with problems ; http://www.haskell.org//pipermail/cvs-all/ - mkdir c:/fptools; cd c:/fptools - ; (or whereever you want your cvs tree to be) - - export CVSROOT=:pserver:anoncvs@cvs.haskell.org:/cvs - - cvs login - ; pw: cvs - - cvs checkout fpconfig - - cd fptools - - cvs checkout ghc hslibs libraries + ; (or whereever you want your darcs tree to be) + - darcs get http://darcs.haskell.org/ghc + - cd ghc + - chmod +x darcs-all + - ./darcs-all get - Build ghc, using cygwin and mingw, targetting mingw - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH