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