README.md 9.22 KB
Newer Older
Andrey Mokhov's avatar
Andrey Mokhov committed
1 2
Hadrian
=======
Andrey Mokhov's avatar
Andrey Mokhov committed
3

Andrey Mokhov's avatar
Andrey Mokhov committed
4
[![Linux & OS X status](https://img.shields.io/travis/snowleopard/hadrian/master.svg?label=Linux%20%26%20OS%20X)](https://travis-ci.org/snowleopard/hadrian) [![Windows status](https://img.shields.io/appveyor/ci/snowleopard/hadrian/master.svg?label=Windows)](https://ci.appveyor.com/project/snowleopard/hadrian) [![OS X status](https://img.shields.io/circleci/project/github/snowleopard/hadrian.svg?label=OS%20X)](https://circleci.com/gh/snowleopard/hadrian)
Andrey Mokhov's avatar
Andrey Mokhov committed
5

Andrey Mokhov's avatar
Andrey Mokhov committed
6
Hadrian is a new build system for the [Glasgow Haskell Compiler][ghc]. It is based
Andrey Mokhov's avatar
Andrey Mokhov committed
7 8
on [Shake][shake] and we hope that it will soon replace the current
[Make-based build system][make]. If you are curious about the rationale behind the
9
project and the architecture of the build system you can find more details in
10 11
this [Haskell Symposium 2016 paper](https://dl.acm.org/authorize?N41275) and this
[Haskell eXchange 2016 talk][talk].
12

13 14
The new build system can work side-by-side with the existing build system. Note, there is
some interaction between them: they put (some) build results in the same directories,
Andrey Mokhov's avatar
Andrey Mokhov committed
15
e.g. the resulting GHC is `inplace/bin/ghc-stage2`.
16

17 18 19
Your first build
----------------

20
Beware, the build system is in the alpha development phase. Things are shaky and sometimes
21
break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
22
run the following command from root of the GHC tree:
23

24 25 26 27 28
```
hadrian/build.sh -j
```

or on Windows:
29

30 31 32
```
hadrian/build.bat -j
```
33

34
Here flag `-j` enables parallelism and is optional. We will further refer to the build script
35 36 37
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.
38

39
Notes:
40

41 42
* 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
43
(`build.global-db.*`). Also see [instructions for building GHC on Windows using Stack][windows-build].
Andrey Mokhov's avatar
Andrey Mokhov committed
44

45 46
* Hadrian is written in Haskell and depends on `shake` (plus a few packages that `shake` depends on),
`ansi-terminal`, `mtl`, `quickcheck`, and GHC core libraries.
47 48

* If you have never built GHC before, start with the [preparation guide][ghc-preparation].
49 50 51

Using the build system
----------------------
Andrey Mokhov's avatar
Andrey Mokhov committed
52 53
Once your first build is successful, simply run `build` to rebuild. Build results
are placed into `_build` and `inplace` directories.
54

55
#### Command line flags
56 57 58

In addition to standard Shake flags (try `--help`), the build system
currently supports several others:
59 60 61 62 63 64 65 66 67 68 69

* `--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):
    ```bash
    ./boot
    ./configure # On Windows run ./configure --enable-tarballs-autodownload
    ```
    Beware that with this flag Hadrian may do network I/O on Windows to download necessary
    tarballs, which may sometimes be undesirable.

70 71 72 73 74
* `--flavour=FLAVOUR`: choose a build flavour. The following settings are currently supported:
`default`, `quick`, `quickest`, `perf`, `prof`, `devel1` and `devel2`. As an example, the
`quickest` flavour adds `-O0` flag to all GHC invocations and builds libraries only in the
`vanilla` way, which speeds up builds by 3-4x. Build flavours are documented
[here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md).
75

Andrey Mokhov's avatar
Andrey Mokhov committed
76 77 78 79 80 81
* `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its source files
are out-of-date. This allows to significantly reduce the rebuild time when you are working
on a feature that affects both Stage1 and Stage2 compilers, but may lead to incorrect
build results. To unfreeze Stage1 GHC simply drop the `--freeze1` flag and Hadrian will
rebuild all out-of-date files.

82 83 84
* `--integer-simple`: build GHC using the `integer-simple` integer library (instead
of `integer-gmp`).

85 86 87 88 89
* `--progress-colour=MODE`: choose whether to use colours when printing build progress
info. There are three settings: `never` (do not use colours), `auto` (attempt to detect
whether the console supports colours; this is the default setting), and `always` (use
colours).

90
* `--progress-info=STYLE`: choose how build progress info is printed. There are four
91 92
settings: `none`, `brief` (one line per build command; this is the default setting),
`normal` (typically a box per build command), and `unicorn` (when `normal` just won't do).
93

94 95 96
* `--split-objects`: generate split objects, which are switched off by default. Due to
a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.

Andrey Mokhov's avatar
Andrey Mokhov committed
97 98 99
* `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
by Shake oracles.

100
#### User settings
101

Andrey Mokhov's avatar
Andrey Mokhov committed
102
The Make-based build system uses `mk/build.mk` to specify user build settings. We
Andrey Mokhov's avatar
Andrey Mokhov committed
103
use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user-settings.md).
104

105
#### Clean and full rebuild
106

107
* `build clean` removes all build artefacts.
108

Andrey Mokhov's avatar
Andrey Mokhov committed
109 110
* `build -B` forces Shake to rerun all rules, even if the previous build results are
are still up-to-date.
111

112 113
#### Documentation

114 115 116
To build GHC documentation, run `build docs`. Note that finer-grain documentation
targets (e.g. building only HTML documentation or only the GHC User's Guide)
are currently not supported.
117

118 119
#### Source distribution

120
To build a GHC source distribution tarball, run `build sdist-ghc`.
Andrey Mokhov's avatar
Andrey Mokhov committed
121

Zhen Zhang's avatar
Zhen Zhang committed
122 123
#### Installation

124
To build and install GHC artifacts, run `build install`.
Zhen Zhang's avatar
Zhen Zhang committed
125

Andrey Mokhov's avatar
Andrey Mokhov committed
126 127 128 129 130 131
By default, GHC will be installed to the specified _prefix_ path on your system,
relative to the root of the file system. For example on UNIX, GHC will be installed
to `/usr/local/bin`. By setting the command line flag `--install-destdir=[DESTDIR]`,
you can install GHC to path `DESTDIR/<prefix>` instead. Make sure you use correct
absolute path as `DESTDIR` on Windows, e.g. `C:/path`, which installs GHC
into `C:/path/usr/local`.
Zhen Zhang's avatar
Zhen Zhang committed
132

Andrey Mokhov's avatar
Andrey Mokhov committed
133 134
#### Testing

135 136 137
* `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
directory. This can be used instead of `sh validate --fast --no-clean` in the existing
build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
138

139 140 141
* `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
script with appropriate flags. The current implementation is limited and cannot
replace the `validate` script (see [#187][validation-issue]).
Andrey Mokhov's avatar
Andrey Mokhov committed
142

143 144
* `build selftest` runs tests of the build system. Current test coverage is close to
zero (see [#197][test-issue]).
145

146 147 148
Current limitations
-------------------
The new build system still lacks many important features:
149
* Validation is not implemented: [#187][validation-issue].
Zhen Zhang's avatar
Zhen Zhang committed
150
* Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
Andrey Mokhov's avatar
Andrey Mokhov committed
151
* There is no support for binary distribution: [#219][bin-dist-issue].
152

Andrey Mokhov's avatar
Andrey Mokhov committed
153 154
Check out [milestones] to see when we hope to resolve the above limitations.

155 156
How to contribute
-----------------
157 158

The best way to contribute is to try the new build system, report the issues
Andrey Mokhov's avatar
Andrey Mokhov committed
159 160 161
you found, and attempt to fix them. Please note: the codebase is very unstable
at present and we expect a lot of further refactoring. If you would like to
work on a particular issue, please let everyone know by adding a comment about
Andrey Mokhov's avatar
Andrey Mokhov committed
162 163
this. The issues that are currently on the critical path and therefore require
particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239).
Andrey Mokhov's avatar
Andrey Mokhov committed
164 165
Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
where open issues and pull requests are grouped into categories.
166

167 168 169 170
Acknowledgements
----------------

I started this project as part of my 6-month research visit to Microsoft
Andrey Mokhov's avatar
Andrey Mokhov committed
171
Research Cambridge, which was funded by Newcastle University, EPSRC, and
172
Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
173
and Simon Marlow for kick-starting the project and for their guidance.
174 175 176 177 178
Zhen Zhang has done fantastic work on Hadrian as part of his Summer of
Haskell 2017 [project](https://summer.haskell.org/ideas.html#hadrian-ghc),
solving a few heavy and long-overdue issues. Last but not least, big thanks
to all other project [contributors][contributors], who helped me endure and
enjoy the project.
179 180

[ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
Andrey Mokhov's avatar
Andrey Mokhov committed
181
[shake]: https://github.com/ndmitchell/shake
182
[make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
183
[talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
Andrey Mokhov's avatar
Andrey Mokhov committed
184
[issues]: https://github.com/snowleopard/hadrian/issues
185 186
[ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
[ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
Andrey Mokhov's avatar
Andrey Mokhov committed
187
[windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
188
[ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
Andrey Mokhov's avatar
Andrey Mokhov committed
189 190
[test-issue]: https://github.com/snowleopard/hadrian/issues/197
[validation-issue]: https://github.com/snowleopard/hadrian/issues/187
Zhen Zhang's avatar
Zhen Zhang committed
191
[dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
Andrey Mokhov's avatar
Andrey Mokhov committed
192
[bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
Andrey Mokhov's avatar
Andrey Mokhov committed
193 194
[milestones]: https://github.com/snowleopard/hadrian/milestones
[contributors]: https://github.com/snowleopard/hadrian/graphs/contributors