From 78bdcf14e059dc193bde45fb7274536f29a5ef79 Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Fri, 20 Jan 2006 15:13:22 +0000 Subject: [PATCH] remove old CVS stuff, replace with darcs --- ghc/docs/building/building.xml | 810 ++-------------------------------------- 1 file changed, 25 insertions(+), 785 deletions(-) diff --git a/ghc/docs/building/building.xml b/ghc/docs/building/building.xml index 6829b1b..aab0e12 100644 --- a/ghc/docs/building/building.xml +++ b/ghc/docs/building/building.xml @@ -59,784 +59,27 @@ - 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 GHC 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 . - - 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). - - Things to check before you start @@ -1246,17 +489,17 @@ $ cvs checkout nofib/spectral - Happy + Happy Happy Happy is a parser generator tool for Haskell, and is used to generate GHC's parsers. - If you start from a source tarball of GHC (i.e. not a CVS + 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 CVS checkout, then you + 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. @@ -1282,10 +525,10 @@ $ cvs checkout nofib/spectral 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 CVS checkout. + building a darcs checkout. Alex is - written in Haskell and is a project in the CVS repository. + written in Haskell and is a project in the darcs repository. Alex distributions are available from Alex's Web Page. @@ -1298,7 +541,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. @@ -1614,7 +857,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 @@ -1858,7 +1101,7 @@ $ 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 @@ -4286,7 +3529,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: @@ -4309,7 +3552,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, @@ -4508,7 +3751,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 @@ -4859,8 +4102,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 . @@ -5001,18 +4243,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 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 -- 1.7.10.4