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

1 files changed, 179 insertions, 0 deletions

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
+  ```