Commit b0074103 authored by Alp Mestanogullari's avatar Alp Mestanogullari 🦑 Committed by Ben Gamari

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
parent 126aa794
......@@ -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.
......
# 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
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment