Skip to content

Changes

Page history
add a lot more documentation authored by alpmestan's avatar alpmestan
Hide whitespace changes
Inline Side-by-side
building/hadrian/quick-start.md
View page @ 590de24a
......@@ -14,13 +14,18 @@ Hadrian is much younger than GHC's Make-based build system. If you need a featur
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`.
- Hadrian can also run `boot` and `configure` for you, with the `-c` flag.
- 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 stage1).
- 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 now relocatable. 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.
You can now directly jump [here](building/hadrian/quick-start#) to see the table listing usual make commands and their hadrian equivalents.
## Your first build
......@@ -53,11 +58,68 @@ Windows users might want to read through [ building GHC on Windows using Stack](
**From now on, this page assumes you have found a build script that works for you and will refer to it as just `build`.**
## Migrating from the Make build system
Below is an equivalence table between make and hadrian commands, with a short description of what the commands do.
<table><tr><th> make command </th>
<th> hadrian command </th>
<th> description
</th></tr>
<tr><th>`make`</th>
<th>`build`</th>
<th> Build a complete stage2 compiler with libraries and with the default flavour (`perf`)
</th></tr>
<tr><th>`make inplace/bin/ghc-stage1`</th>
<th>`build _build/stage0/bin/ghc`</th>
<th> Build a stage1 GHC executable
</th></tr>
<tr><th>`make inplace/bin/ghc-stage2`</th>
<th>`build _build/stage1/bin/ghc`</th>
<th> Build a stage2 GHC executable
</th></tr>
<tr><th>`make inplace/lib/package.conf.d/text-1.2.3.0.conf`</th>
<th>`build _build/stage1/lib/package.conf.d/text-1.2.3.0.conf`</th>
<th> Build and register text-1.2.3.0.conf with the stage2 haskell compiler
</th></tr>
<tr><th>`make inplace/lib/platformConstants`</th>
<th>`build _build/stage{0,1}/lib/platformConstants`</th>
<th> Generate the `platformConstants` file to be used for stage 1 or stage 2 GHC
</th></tr>
<tr><th>`make libraries/base/dist-install/build/libHSbase-4.12.0.0.a`</th>
<th>`build _build/stage1/libraries/base/build/libHSbase-4.12.0.0.a`</th>
<th> Build static library for `base` with the stage 1 compiler
</th></tr>
<tr><th>`make docs`</th>
<th>`build docs`</th>
<th> Generate haddocks, user guide and more
</th></tr>
<tr><th>`make clean ; make boot ; make 2>&1 | tee nofib-log`</th>
<th>`build nofib`</th>
<th> Run the nofib suite (building a compiler if necessary)
</th></tr>
<tr><th>*Setting `BuildFlavour=quickest` in build.mk*</th>
<th>`build --flavour=quickest`</th>
<th> Build a `quickest`-flavoured stage 2 compiler
</th></tr>
<tr><th>`make test`</th>
<th>`build test`</th>
<th> Run the testsuite
</th></tr>
<tr><th>`make test TEST=abcd`</th>
<th>`build test --only=abcd`</th>
<th> Run only the test named `abcd`</th></tr>
<tr><th> N/A </th>
<th>`build --build-root=ghc-T9999`</th>
<th> Build a complete stage2 compiler under a user specified build root (`./ghc-T9999/` here). Hadrian places all build artifacts under that directory
</th></tr></table>
## Command line options
In addition to standard Shake flags (try `--help`), the build system
currently supports several others:
currently supports several many others, among which the important ones described below. Please refer to `build --help` for a complete listing of the command line arguments supported by hadrian.
- `--build-root=PATH` or `-oPATH`: specify the directory in which you want to store all the build artifacts. If none is specified by the user, hadrian will store everything under `_build/` at the top of ghc's source tree. Unlike GHC's 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 directory, and have the build products sit in different, isolated folders.
......@@ -83,51 +145,19 @@ currently supports several others:
- `--split-objects`: generate split objects, which are switched off by default. Due to a GHC [ bug](https://ghc.haskell.org/trac/ghc/ticket/11315), you need a full clean rebuild when using this flag.
- `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages by Shake oracles.
## Build targets
If no target is specified on the command line, like in the commands at the beginning of this page, Hadrian builds a complete stage 2 GHC with the `perf` build flavour. You can however specify specific targets, by simply giving the path to one or more files you want to generate or "build" in a general sense, or by specifying phony targets. When given specific targets, Hadrian will only build what it needs to produce the targets you ask for, just like the Make build system.
Some examples:
```
# build a stage 1 ghc binary
$ build _build/stage0/bin/ghc
# or, with a custom build root:
$ build --build-root=_feature _feature/stage0/bin/ghc
- `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages by Shake oracles, useful when debugging hadrian.
# build and register stage 2 text, version 1.2.3.0
$ build _build/stage1/lib/package.conf.d/text-1.2.3.0.conf
- `--test-compiler[=TEST_COMPILER]`: use the given compiler (default is stage2) for running the testsuite, when executing the `test` target. `TEST_COMPILER` can be `stage1, stage2` or even the path to some arbitrary ghc executable.
# generate the 'platformConstants' file for stage 1 ghc
$ build _build/stage0/lib/platformConstants
- `--only[=TESTS]`: only run the given test cases, e.g `--only="T123 T456"`.
# build the static library for stage 2 base
$ build _build/stage1/libraries/base/build/libHSbase-4.11.1.0.a
# phony target for building haddocks, user guide and more
$ build docs
# phony target for producing a binary distribution
# note: they are not as complete as the ones the make build
# system produces yet.
$ build binary-dist
# phony target for producing a source distribution
$ build source-dist
- `--skip-perf`: skip performance tests.
# phony targets for running tests or validate
# note: those are quite incomplete and buggy at the moment,
# see https://github.com/snowleopard/hadrian/issues/187
$ build test
$ build validate
```
- `--test-speed[=SPEED]`: `fast`, `slow` or `normal` (Normal by default). They respectively correspond to `make fasttest`, `make slowtest` and `make test`.
- `--summary[=TEST_SUMMARY]`: where to output the test summary file.
Once you have a full build of GHC, you can take a look at the files produced under the build root to see where all the build artifacts you might care about reside.
- `--test-way[=TEST_WAY]`: only run these test ways, e.g `--test-way=threaded2`.
## User settings
......@@ -147,4 +177,21 @@ Hadrian is a submodule of the main GHC git repository, located at the root of th
$ cd hadrian
$ git remote add snowleopard https://github.com/snowleopard/hadrian.git
$ git fetch snowleopard && git checkout snowleopard/master
```
## Build targets to be documented
```
# phony target for producing a binary distribution
# note: they are not as complete as the ones the make build
# system produces yet.
$ build binary-dist
# phony target for producing a source distribution
$ build source-dist
# phony target for running validate
# note: those are quite incomplete and buggy at the moment,
# see https://github.com/snowleopard/hadrian/issues/187
$ build validate
```
\ No newline at end of file