diff --git a/hadrian/README.md b/hadrian/README.md
index c88d98e99df6e20214797e438014a88bd666bfe2..16a26d0cbeba0bc750aa02cbb69a1435055bb95c 100644
--- a/hadrian/README.md
+++ b/hadrian/README.md
@@ -18,56 +18,62 @@ if you'd like to start using Hadrian for building GHC.
Your first build
----------------
-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 has not entirely caught up with the make build system. Not afraid?
+Then put on the helmet and run the following commands from the root of the GHC
+tree:
```
+./boot && ./configure
hadrian/build.sh -j
```
or on Windows:
```
+./boot && ./configure --enable-tarballs-autodownload
hadrian/build.bat -j
```
-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.
+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 for you if you pass the flag `--configure`,
+or simply `-c`. See the 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].
+* 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.*`) or
+Stack (`build.stack.*`). 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].
+* 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
----------------------
-Once your first build is successful, simply run `build` to rebuild. Build results
-are placed into `_build` and `inplace` directories.
+Once your first build is successful, simply run `build` to rebuild after some
+changes. Build results are placed into `_build` by default.
#### Command line flags
In addition to standard Shake flags (try `--help`), the build system
currently supports several others:
-* `--build-root=PATH` or `-oPATH`: specify the directory in which you want to store all
-build products. By default Hadrian builds everything in the `_build/` subdirectory of
-the GHC source tree. Unlike the Make build system, Hadrian doesn't have any "inplace"
-logic left anymore. This option is therefore useful for GHC developers who want to build
-GHC in different ways or at different commits, from the same source directory, and have
-the build products sit in different, isolated folders.
+* `--build-root=PATH` or `-oPATH`: specify the directory in which you want to
+store all build products. By default Hadrian builds everything in the `_build/`
+subdirectory of the GHC source tree. Unlike the Make build system, Hadrian
+doesn't have any "inplace" logic left anymore. This option is therefore useful
+for GHC developers who want to build GHC in different ways or at different
+commits, from the same source directory, and have the build products sit in
+different, isolated folders.
* `--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):
+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
@@ -140,6 +146,15 @@ build stage2:lib:text
build stage2:exe:haddock
```
+#### Testing
+
+To run GHC's testsuite, use `build test`. See
+[doc/testsuite.md](doc/testsuite.md) to learn about all the options
+you can use to mimic what the Make build system offers.
+
+`build selftest` runs tests of the build system. Current test coverage
+is close to zero (see [#197][test-issue]).
+
#### Clean and full rebuild
* `build clean` removes all build artefacts.
@@ -168,25 +183,10 @@ $ ./configure [--prefix=PATH] && make install
workflow, for now.
-#### Testing
-
-To run GHC's testsuite, use `build test`. See
-[doc/testsuite.md](doc/testsuite.md) to learn about all the options
-you can use to mimic what the Make build system offers.
-
-`build selftest` runs tests of the build system. Current test coverage
-is close to zero (see [#197][test-issue]).
-
Troubleshooting
---------------
Here are a few simple suggestions that might help you fix the build:
-
-* The Hadrian submodule in GHC is occasionally behind the master branch of this repository,
- which contains most recent bug fixes. To switch to the most recent version of Hadrian,
- run `git pull https://github.com/snowleopard/hadrian.git`. Beware: the most recent version
- contains the most recent bugs too! If this works, please raise an issue and we will try to
- push the changes to the GHC submodule as soon as possible.
* Hadrian is occasionally broken by changes in GHC. If this happens, you might want to switch
to an earlier GHC commit.
@@ -204,7 +204,6 @@ 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.
diff --git a/hadrian/doc/make.md b/hadrian/doc/make.md
new file mode 100644
index 0000000000000000000000000000000000000000..ca4828a48439602e941474e4a10be062c20bb555
--- /dev/null
+++ b/hadrian/doc/make.md
@@ -0,0 +1,179 @@
+# Hadrian for Make users
+
+## tl;dr
+
+For GHC hackers already used to the Make build system, here is what you need to
+know:
+
+- You can still boot and configure yourself.
+- Use `hadrian/build.{sh, bat}` instead of `make`. It supports `-j`. This build
+ script will from now on be referred to as simply `build`.
+- Add the `-c` flag if you want hadrian to boot and configure the source tree
+ for you.
+- Build products are not in `inplace` anymore, but `_build` by default. Your
+ stage 2 GHC would then be at `_build/stage1/bin/ghc` (because it's built by
+ the stage 1 compiler).
+- The build root is configurable with `--build-root` or `-o`.
+- You can pick the build flavour with `--flavour=X` where X is `perf`, `prof`,
+ etc.
+- You can run tests with `build test`, and specific ones by adding
+ `--only="T12345 T11223"` for example.
+- GHCs built by Hadrian are relocatable on Windows, Linux, OS X and FreeBSD.
+ This means you can move the `<build root>/stage1/{lib, bin}` directories
+ around and GHC will still happily work, as long as both directories stay next
+ to each other.
+
+Of particular interest is the `--build-root/-o` option, which is often useful to
+work on different things or build GHC in different ways, from the same
+directory/GHC checkout, without having to sacrifice the build artifacts every
+time you fire up a build. This is not possible with the Make build system.
+
+## Equivalent commands
+
+- Building a complete stage 2 compiler with its libraries, default flavour
+
+ ``` sh
+ # Make
+ make
+
+ # Hadrian
+ build
+ ```
+
+- Building with many cores
+
+ ``` sh
+ # Make
+ make -j8
+
+ # Hadrian
+ build -j8
+ ```
+
+- Bulding a stage 1 or 2 GHC executable
+
+ ``` sh
+ # Make
+ make inplace/bin/ghc-stage1
+ make inplace/bin/ghc-stage2
+
+ # Hadrian
+ build stage1:exe:ghc-bin # using the simple target name
+ build _build/stage0/bin/ghc # OR using the actual path
+
+ build stage2:exe:ghc-bin # simple target
+ build _build/stage1/bin/ghc # OR actual path
+ ```
+
+- Building and registering a library with the stage 2 compiler
+
+ ``` sh
+ # Make
+ make inplace/lib/package.conf.d/text-1.2.3.0.conf
+
+ # Hadrian
+ build stage2:lib:text # simple target
+ build _build/stage1/lib/package.conf.d/text-1.2.3.0.conf # OR actual path
+ ```
+
+- Building with a particular flavour (e.g `quickest`)
+
+ ``` sh
+ # Make
+ echo "BuildFlavour=quickest" >> mk/build.mk
+ make
+
+ # Hadrian
+ build --flavour=quickest
+ ```
+
+- Building with `integer-simple` as the integer library
+
+ ``` sh
+ # Make
+ echo "INTEGER_LIBRARY=integer-simple" >> mk/build.mk
+ make
+
+ # Hadrian
+ build --integer-simple
+ ```
+
+- Freezing the stage 1 GHC compiler
+
+ ``` sh
+ # Make
+ echo "stage=2" >> mk/build.mk
+ make
+
+ # Hadrian
+ build --freeze1
+ ```
+
+- Running the testsuite
+
+ ``` sh
+ # Make
+ make test # (1)
+ make test TEST=plugins01 # (2)
+ make test TEST="plugins01 plugins02" # (3)
+
+
+ # Hadrian
+ build test # equivalent to (1)
+
+ build test --only=plugins01 # equivalent to (2)
+ TEST=plugins01 build test # equivalent to (2)
+
+ build test --only="plugins01 plugins02" # equivalent to (3)
+ TEST="plugins01 plugins02" build test # equivalent to (3)
+ TEST=plugins01 build test --only=plugins02 # equivalent to (3)
+ ```
+
+ As illustrated in the examples above, you can use the `TEST` environment
+ variable, the `--only=...` flag or even both to restrict your testsuite run
+ to some (usually small) subset of the testsuite.
+
+ See [the docs for the test rules](./testsuite.md) if you want to know about
+ all the options that hadrian supports and what they correspond to in the Make
+ build system.
+
+- Generate the `platformConstants` file to be used for stage 1/2 GHC
+
+ ``` sh
+ # Make
+ make inplace/lib/platformConstants
+
+ # Hadrian
+ build _build/stage0/lib/platformConstants
+ build _build/stage1/lib/platformConstants
+ ```
+
+- Build a static library for base with the stage 1 compiler
+
+ ``` sh
+ # Make
+ make libraries/base/dist-install/build/libHSbase-4.12.0.0.a
+
+ # Hadrian
+ build _build/stage1/libraries/base/build/libHSbase-4.12.0.0.a
+ ```
+
+- Generate haddocks, user guide, etc
+
+ ``` sh
+ # Make
+ make docs
+
+ # Hadrian
+ build docs
+ ```
+
+- Running nofib
+
+ ``` sh
+ # Make
+ cd nofib; make clean; make boot; make 2>&1 | tee nofib-log
+
+ # Hadrian
+ build nofib # builds the compiler and everything we need if necessary, too
+ ```