[WIP] Support run GHC's test from hadrian. (#495)
[hadrian.git] / README.md
index 2530714..23e8586 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,44 +4,48 @@ Hadrian
 [![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)
 
 Hadrian is a new build system for the [Glasgow Haskell Compiler][ghc]. It is based
-on [Shake][shake] and we hope that it will eventually replace the current
-[`make`-based build system][make]. If you are curious about the rationale behind the
+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 [Haskell Symposium 2016 paper](https://dl.acm.org/authorize?N41275) and this
+[Haskell eXchange 2016 talk][talk].
 
 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. `inplace/bin/ghc-stage1`.
+e.g. the resulting GHC is `inplace/bin/ghc-stage2`.
 
 Your first build
 ----------------
 
-Beware, the build system is in the alpha development phase. Things are shaky and often
+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
-follow these steps:
+run the following command from root of the GHC tree:
 
-* If you have never built GHC before, start with the [preparation guide][ghc-preparation].
+```
+hadrian/build.sh -j
+```
 
-* This build system is written in Haskell (obviously) and depends on the following Haskell
-packages, which need to be installed: `ansi-terminal extra mtl quickcheck shake`.
+or on Windows:
 
-* Get the sources. It is important for the build system to be in the `hadrian` directory
-of the GHC source tree:
+```
+hadrian/build.bat -j
+```
 
-    ```bash
-    git clone --recursive git://git.haskell.org/ghc.git
-    cd ghc
-    git clone git://github.com/snowleopard/hadrian
-    ```
+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.
 
-* Build GHC using `hadrian/build.sh` or `hadrian/build.bat` (on Windows) instead
-of `make`. You might want to enable parallelism with `-j`. We will further refer to the
-build script simply as `build`. If you are interested in building in a Cabal sandbox
-or using Stack, have a look at `build.cabal.sh` and `build.stack.sh` scripts. Also
-see [instructions for building GHC on Windows using Stack][windows-build]. Note, Hadrian
-runs the `boot` and `configure` scripts automatically on the first build, so that you don't
-need to. Use `--skip-configure` to suppress this behaviour (see overview of command line
-flags below).
+Notes:
+
+* 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].
+
+* Hadrian is written in Haskell and depends on `shake` (plus a few packages that `shake` depends on),
+`mtl`, `quickcheck`, and GHC core libraries.
+
+* If you have never built GHC before, start with the [preparation guide][ghc-preparation].
 
 Using the build system
 ----------------------
@@ -52,6 +56,17 @@ are placed into `_build` and `inplace` directories.
 
 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.
+
 * `--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
@@ -64,8 +79,6 @@ on a feature that affects both Stage1 and Stage2 compilers, but may lead to inco
 build results. To unfreeze Stage1 GHC simply drop the `--freeze1` flag and Hadrian will
 rebuild all out-of-date files.
 
-* `--haddock`: build Haddock documentation.
-
 * `--integer-simple`: build GHC using the `integer-simple` integer library (instead
 of `integer-gmp`).
 
@@ -78,18 +91,6 @@ colours).
 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).
 
-* `--skip-configure`: use this flag to suppress the default behaviour of Hadrian that
-runs the `boot` and `configure` scripts automatically if need be, so that you don't have
-to remember to run them manually. With `--skip-configure` you will need to manually run:
-
-    ```bash
-    ./boot
-    ./configure # On Windows run ./configure --enable-tarballs-autodownload
-    ```
-as you normally do when using `make`. Beware, by default Hadrian may do network I/O on
-Windows to download necessary tarballs, which may sometimes be undesirable; `--skip-configure`
-is your friend in such cases.
-
 * `--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.
 
@@ -98,7 +99,7 @@ by Shake oracles.
 
 #### User settings
 
-The `make`-based build system uses `mk/build.mk` to specify user build settings. We
+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
@@ -108,20 +109,26 @@ use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user
 * `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 Hadrian with the `sdist-ghc` target.
+To build a GHC source distribution tarball, run `build sdist-ghc`.
 
 #### Installation
 
-To build and install GHC artifacts, run the `install` target.
+To build and install GHC artifacts, run `build install`.
 
-By default, the artifacts will be installed to `<prefix>` on your system
-(in this case, the `DESTDIR` is empty, corresponds to the root of the file system).
-For example on UNIX, `ghc` will be installed to `/usr/local/bin`. By setting flag `--install-destdir=[DESTDIR]`,
-you can install things to non-system path `DESTDIR/<prefix>` instead.
-Make sure you use correct absolute path on Windows, e.g. `C:/path`,
-i.e. GHC is installed into `C:/path/usr/local` for the above example.
+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
 
@@ -141,9 +148,7 @@ 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].
-* Only HTML Haddock documentation is supported (use `--haddock` flag).
-* Cross-compilation is not implemented: [#177][cross-compilation-issue].
-* There is no support for binary distribution: [#219][install-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.
 
@@ -173,9 +178,8 @@ 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/blob/master/README.md
+[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
@@ -185,7 +189,6 @@ enjoy the project.
 [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
-[cross-compilation-issue]: https://github.com/snowleopard/hadrian/issues/177
-[install-issue]: https://github.com/snowleopard/hadrian/issues/219
+[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