Furher work on monadic tcTypeKind
[ghc.git] / README.md
index f5b8117..02bf4a8 100644 (file)
--- a/README.md
+++ b/README.md
-Shaking up GHC
-==============
+The Glasgow Haskell Compiler
+============================
 
-[![Linux & OS X status](https://img.shields.io/travis/snowleopard/shaking-up-ghc.svg?label=Linux%20%26%20OS%20X)](https://travis-ci.org/snowleopard/shaking-up-ghc) [![Windows status](https://img.shields.io/appveyor/ci/snowleopard/shaking-up-ghc.svg?label=Windows)](https://ci.appveyor.com/project/snowleopard/shaking-up-ghc)
+[![Build Status](https://api.travis-ci.org/ghc/ghc.svg?branch=master)](http://travis-ci.org/ghc/ghc)
 
+This is the source tree for [GHC][1], a compiler and interactive
+environment for the Haskell functional programming language.
 
-As part of my 6-month research secondment to Microsoft Research in Cambridge
-I am taking up the challenge of migrating the current [GHC][ghc] build system
-based on standard `make` into a new and (hopefully) better one based on
-[Shake][shake]. If you are curious about the project you can find more details
-on the [wiki page][ghc-shake-wiki] and in this [blog post][shake-blog-post].
+For more information, visit [GHC's web site][1].
 
-This is supposed to go into the `shake-build` directory of the GHC source tree.
+Information for developers of GHC can be found on the [GHC Trac][2].
 
-[Join us on #shaking-up-ghc on Freenode](irc://chat.freenode.net/#shaking-up-ghc).
 
-Trying it
----------
+Getting the Source
+==================
 
-Please see the [Preparation][ghc-preparation] on the GHC wiki
-for general preparation. The preparation steps for the `shake` build system are
-identical to those for the `make` build system. This means that you don't need
-to adjust anything if you are already familiar with building ghc using the `make`
-build system.
+There are two ways to get a source tree:
 
-Furthermore, we depend on the following packages which need to be installed:
-`ansi-terminal`, `mtl`, `shake`, `QuickCheck`.
+ 1. *Download source tarballs*
 
-### Getting the source and configuring GHC
+  Download the GHC source distribution:
 
-```bash
-git clone --recursive git://git.haskell.org/ghc.git
-cd ghc
-git clone git://github.com/snowleopard/shaking-up-ghc shake-build
-./boot
-./configure                                # on linux / os x
-./configure --enable-tarballs-autodownload # on windows
-```
+        ghc-<version>-src.tar.bz2
 
-### Configuring the build process
+  which contains GHC itself and the "boot" libraries.
 
-`ghc` uses `mk/build.mk` to configure the build process. `shaking-up-ghc`
-uses `src/Settings/User.hs` for build specification.
+ 2. *Check out the source code from git*
 
-### Building GHC using `shaking-up-ghc`
+        $ git clone --recursive git://git.haskell.org/ghc.git
 
-```bash
-./shake-build/build.sh       # linux / os x: to run the script directly.
-./shake-build/build.cabal.sh # linux / os x: OR to install the build system in a Cabal sandbox and then run it.
-shake-build/build.bat        # windows
-```
+  Note: cloning GHC from Github requires a special setup. See [Getting a GHC
+  repository from Github][7].
 
-Also see the [Building GHC on Windows guide][ghc-windows-building-guide].
+  *See the GHC team's working conventions regarding [how to contribute a patch to GHC](http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/FixingBugs).* First time contributors are encouraged to get started by just sending a Pull Request.
 
-### Resetting the build
 
-To reset the new build system run the build script with `-B` flag. This forces Shake to rerun all rules, even if results of the previous build are still in the GHC tree. This is a temporary solution; we are working on a proper reset functionality ([#131](https://github.com/snowleopard/shaking-up-ghc/issues/131)).
+Building & Installing
+=====================
 
+For full information on building GHC, see the [GHC Building Guide][3].
+Here follows a summary - if you get into trouble, the Building Guide
+has all the answers.
 
-How to contribute
------------------
+Before building GHC you may need to install some other tools and
+libraries.  See, [Setting up your system for building GHC][8].
 
-The best way to contribute is to try the new build system, report the issues
-you found, and attempt to fix them. Please note the codebase is very unstable
-at present and we expect a lot of further refactoring. Before attempting to
-fix any issue do make sure no one else is already working on it. The
-documentation is currently non-existent, but we will start addressing this
-once the codebase stabilises.
+*NB.* In particular, you need [GHC][1] installed in order to build GHC,
+because the compiler is itself written in Haskell.  You also need
+[Happy][4], [Alex][5], and [Cabal][9].  For instructions on how
+to port GHC to a new platform, see the [GHC Building Guide][3].
 
+For building library documentation, you'll need [Haddock][6].  To build
+the compiler documentation, you need [Sphinx](http://www.sphinx-doc.org/)
+and Xelatex (only for PDF output).
 
-[ghc-shake-wiki]: https://ghc.haskell.org/trac/ghc/wiki/Building/Shake
-[ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
-[ghc-windows-building-guide]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows
-[ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
-[shake-blog-post]: https://blogs.ncl.ac.uk/andreymokhov/shaking-up-ghc
-[shake]: https://github.com/ndmitchell/shake/blob/master/README.md
+**Quick start**: the following gives you a default build:
+
+    $ ./boot
+    $ ./configure
+    $ make         # can also say 'make -jX' for X number of jobs
+    $ make install
+
+  On Windows, you need an extra repository containing some build tools.
+  These can be downloaded for you by configure. This only needs to be done once by running:
+
+    $ ./configure --enable-tarballs-autodownload
+
+(NB: **Do you have multiple cores? Be sure to tell that to `make`!** This can
+save you hours of build time depending on your system configuration, and is
+almost always a win regardless of how many cores you have. As a simple rule,
+you should have about N+1 jobs, where `N` is the amount of cores you have.)
+
+The `./boot` step is only necessary if this is a tree checked out
+from git.  For source distributions downloaded from [GHC's web site][1],
+this step has already been performed.
+
+These steps give you the default build, which includes everything
+optimised and built in various ways (eg. profiling libs are built).
+It can take a long time.  To customise the build, see the file `HACKING.md`.
+
+Filing bugs and feature requests
+================================
+
+If you've encountered what you believe is a bug in GHC, or you'd like
+to propose a feature request, please let us know! Submit a ticket in
+our [bug tracker][10] and we'll be sure to look into it. Remember:
+**Filing a bug is the best way to make sure your issue isn't lost over
+time**, so please feel free.
+
+If you're an active user of GHC, you may also be interested in joining
+the [glasgow-haskell-users][11] mailing list, where developers and
+GHC users discuss various topics and hang out.
+
+Hacking & Developing GHC
+========================
+
+Once you've filed a bug, maybe you'd like to fix it yourself? That
+would be great, and we'd surely love your company! If you're looking
+to hack on GHC, check out the guidelines in the `HACKING.md` file in
+this directory - they'll get you up to speed quickly.
+
+Contributors & Acknowledgements
+===============================
+
+GHC in its current form wouldn't exist without the hard work of
+[its many contributors][12]. Over time, it has grown to include the
+efforts and research of many institutions, highly talented people, and
+groups from around the world. We'd like to thank them all, and invite
+you to join!
+
+  [1]:  http://www.haskell.org/ghc/            "www.haskell.org/ghc/"
+  [2]:  http://ghc.haskell.org/trac/ghc    "ghc.haskell.org/trac/ghc"
+  [3]:  http://ghc.haskell.org/trac/ghc/wiki/Building
+          "ghc.haskell.org/trac/ghc/wiki/Building"
+  [4]:  http://www.haskell.org/happy/          "www.haskell.org/happy/"
+  [5]:  http://www.haskell.org/alex/           "www.haskell.org/alex/"
+  [6]:  http://www.haskell.org/haddock/        "www.haskell.org/haddock/"
+  [7]: https://ghc.haskell.org/trac/ghc/wiki/Building/GettingTheSources#GettingaGHCrepositoryfromGitHub
+          "https://ghc.haskell.org/trac/ghc/wiki/Building/GettingTheSources#GettingaGHCrepositoryfromGitHub"
+  [8]:  http://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
+          "http://ghc.haskell.org/trac/ghc/wiki/Building/Preparation"
+  [9]:  http://www.haskell.org/cabal/          "http://www.haskell.org/cabal/"
+  [10]: http://ghc.haskell.org/trac/ghc/
+          "http://ghc.haskell.org/trac/ghc/"
+  [11]: http://www.haskell.org/pipermail/glasgow-haskell-users/
+          "http://www.haskell.org/pipermail/glasgow-haskell-users/"
+  [12]: http://ghc.haskell.org/trac/ghc/wiki/TeamGHC
+          "http://ghc.haskell.org/trac/ghc/wiki/TeamGHC"