Fix README

This was unfortunately overwritten by the Hadrian README in a previous
Hadrian merge.

1 files changed, 106 insertions, 172 deletions

diff --git a/README.md b/README.md
index d188a4a054..02bf4a8f1a 100644
--- a/README.md
+++ b/README.md
@@ -1,194 +1,128 @@
-Hadrian
-=======
+The Glasgow Haskell Compiler
+============================
 
-[![Linux & OS X status](https://img.shields.io/travis/snowleopard/hadrian/master.svg?label=Linux%20%26%20OS%20X)](https://travis-ci.org/snowleopard/hadrian) [![Windows status](https://img.shields.io/appveyor/ci/snowleopard/hadrian/master.svg?label=Windows)](https://ci.appveyor.com/project/snowleopard/hadrian) [![OS X status](https://img.shields.io/circleci/project/github/snowleopard/hadrian.svg?label=OS%20X)](https://circleci.com/gh/snowleopard/hadrian)
+[![Build Status](https://api.travis-ci.org/ghc/ghc.svg?branch=master)](http://travis-ci.org/ghc/ghc)
 
-Hadrian is a new build system for the [Glasgow Haskell Compiler][ghc]. It is based
-on [Shake][shake] and we hope that it will soon replace the current
-[Make-based build system][make]. If you are curious about the rationale behind the
-project and the architecture of the build system you can find more details in
-this [Haskell Symposium 2016 paper][paper] and this [Haskell eXchange 2016 talk][talk].
+This is the source tree for [GHC][1], a compiler and interactive
+environment for the Haskell functional programming language.
 
-The new build system can work side-by-side with the existing build system. Note, there is
-some interaction between them: they put (some) build results in the same directories,
-e.g. the resulting GHC is `inplace/bin/ghc-stage2`.
+For more information, visit [GHC's web site][1].
 
-Your first build
-----------------
+Information for developers of GHC can be found on the [GHC Trac][2].
 
-Beware, the build system is in the alpha development phase. Things are shaky and sometimes
-break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
-run the following command from root of the GHC tree:
 
-```
-hadrian/build.sh -j
-```
+Getting the Source
+==================
 
-or on Windows:
+There are two ways to get a source tree:
 
-```
-hadrian/build.bat -j
-```
+ 1. *Download source tarballs*
 
-Here flag `-j` enables parallelism and is optional. We will further refer to the build script
-simply as `build`. Note that Hadrian can also run the `boot` and `configure` scripts
-automatically if you pass the flag `--configure`, or simply `-c`. See the overview of
-command line flags below.
+  Download the GHC source distribution:
 
-Notes:
+        ghc-<version>-src.tar.bz2
 
-* If the default build script doesn't work, you might want to give a try to another one, e.g. based
-on Cabal sandboxes (`build.cabal.*`), Stack (`build.stack.*`) or the global package database
-(`build.global-db.*`). Also see [instructions for building GHC on Windows using Stack][windows-build].
+  which contains GHC itself and the "boot" libraries.
 
-* Hadrian is written in Haskell and depends on `shake` (plus a few packages that `shake` depends on),
-`ansi-terminal`, `mtl`, `quickcheck`, and GHC core libraries.
+ 2. *Check out the source code from git*
 
-* If you have never built GHC before, start with the [preparation guide][ghc-preparation].
+        $ git clone --recursive git://git.haskell.org/ghc.git
 
-Using the build system
-----------------------
-Once your first build is successful, simply run `build` to rebuild. Build results
-are placed into `_build` and `inplace` directories.
+  Note: cloning GHC from Github requires a special setup. See [Getting a GHC
+  repository from Github][7].
 
-#### Command line flags
+  *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.
 
-In addition to standard Shake flags (try `--help`), the build system
-currently supports several others:
 
-* `--configure` or `-c`: use this flag to run the `boot` and `configure` scripts
-automatically, so that you don't have to remember to run them manually as you normally
-do when using Make (typically only in the first build):
-    ```bash
-    ./boot
-    ./configure # On Windows run ./configure --enable-tarballs-autodownload
-    ```
-    Beware that with this flag Hadrian may do network I/O on Windows to download necessary
-    tarballs, which may sometimes be undesirable.
+Building & Installing
+=====================
 
-* `--flavour=FLAVOUR`: choose a build flavour. The following settings are currently supported:
-`default`, `quick`, `quickest`, `perf`, `prof`, `devel1` and `devel2`. As an example, the
-`quickest` flavour adds `-O0` flag to all GHC invocations and builds libraries only in the
-`vanilla` way, which speeds up builds by 3-4x. Build flavours are documented
-[here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md).
+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.
 
-* `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its source files
-are out-of-date. This allows to significantly reduce the rebuild time when you are working
-on a feature that affects both Stage1 and Stage2 compilers, but may lead to incorrect
-build results. To unfreeze Stage1 GHC simply drop the `--freeze1` flag and Hadrian will
-rebuild all out-of-date files.
+Before building GHC you may need to install some other tools and
+libraries.  See, [Setting up your system for building GHC][8].
 
-* `--integer-simple`: build GHC using the `integer-simple` integer library (instead
-of `integer-gmp`).
+*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].
 
-* `--progress-colour=MODE`: choose whether to use colours when printing build progress
-info. There are three settings: `never` (do not use colours), `auto` (attempt to detect
-whether the console supports colours; this is the default setting), and `always` (use
-colours).
+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).
 
-* `--progress-info=STYLE`: choose how build progress info is printed. There are four
-settings: `none`, `brief` (one line per build command; this is the default setting),
-`normal` (typically a box per build command), and `unicorn` (when `normal` just won't do).
-
-* `--split-objects`: generate split objects, which are switched off by default. Due to
-a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.
-
-* `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
-by Shake oracles.
-
-#### User settings
-
-The Make-based build system uses `mk/build.mk` to specify user build settings. We
-use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user-settings.md).
-
-#### Clean and full rebuild
-
-* `build clean` removes all build artefacts.
-
-* `build -B` forces Shake to rerun all rules, even if the previous build results are
-are still up-to-date.
-
-#### Documentation
-
-To build GHC documentation, run `build docs`. Note that finer-grain documentation
-targets (e.g. building only HTML documentation or only the GHC User's Guide)
-are currently not supported.
-
-#### Source distribution
-
-To build a GHC source distribution tarball, run `build sdist-ghc`.
-
-#### Installation
-
-To build and install GHC artifacts, run `build install`.
-
-By default, GHC will be installed to the specified _prefix_ path on your system,
-relative to the root of the file system. For example on UNIX, GHC will be installed
-to `/usr/local/bin`. By setting the command line flag `--install-destdir=[DESTDIR]`,
-you can install GHC to path `DESTDIR/<prefix>` instead. Make sure you use correct
-absolute path as `DESTDIR` on Windows, e.g. `C:/path`, which installs GHC
-into `C:/path/usr/local`.
-
-#### Testing
-
-* `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
-directory. This can be used instead of `sh validate --fast --no-clean` in the existing
-build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
-
-* `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
-script with appropriate flags. The current implementation is limited and cannot
-replace the `validate` script (see [#187][validation-issue]).
-
-* `build selftest` runs tests of the build system. Current test coverage is close to
-zero (see [#197][test-issue]).
-
-Current limitations
--------------------
-The new build system still lacks many important features:
-* Validation is not implemented: [#187][validation-issue].
-* Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
-* There is no support for binary distribution: [#219][bin-dist-issue].
-
-Check out [milestones] to see when we hope to resolve the above limitations.
-
-How to contribute
------------------
-
-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. If you would like to
-work on a particular issue, please let everyone know by adding a comment about
-this. The issues that are currently on the critical path and therefore require
-particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239).
-Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
-where open issues and pull requests are grouped into categories.
-
-Acknowledgements
-----------------
-
-I started this project as part of my 6-month research visit to Microsoft
-Research Cambridge, which was funded by Newcastle University, EPSRC, and
-Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
-and Simon Marlow for kick-starting the project and for their guidance.
-Zhen Zhang has done fantastic work on Hadrian as part of his Summer of
-Haskell 2017 [project](https://summer.haskell.org/ideas.html#hadrian-ghc),
-solving a few heavy and long-overdue issues. Last but not least, big thanks
-to all other project [contributors][contributors], who helped me endure and
-enjoy the project.
-
-[ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
-[shake]: https://github.com/ndmitchell/shake
-[make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
-[paper]: https://www.staff.ncl.ac.uk/andrey.mokhov/Hadrian.pdf
-[talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
-[issues]: https://github.com/snowleopard/hadrian/issues
-[ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
-[ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
-[windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
-[ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
-[test-issue]: https://github.com/snowleopard/hadrian/issues/197
-[validation-issue]: https://github.com/snowleopard/hadrian/issues/187
-[dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
-[bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
-[milestones]: https://github.com/snowleopard/hadrian/milestones
-[contributors]: https://github.com/snowleopard/hadrian/graphs/contributors
+**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"