hadrian: introduce make-user-oriented docs

This commit introduces Hadrian docs specifically
targeted at GHC devs who are used to building GHC with the make
build system, adapting a good chunk of the following quickstart
page we wrote over the last few months:

  https://ghc.haskell.org/trac/ghc/wiki/Building/Hadrian/QuickStart

Reviewers: snowleopard, bgamari

Reviewed By: snowleopard

Subscribers: rwbarton, carter

Differential Revision: https://phabricator.haskell.org/D5446

2 files changed, 217 insertions, 39 deletions

diff --git a/hadrian/README.md b/hadrian/README.md
index c88d98e99d..16a26d0cbe 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 0000000000..ca4828a484
--- /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
+  ```