README.md 9.44 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
7
on [Shake][shake] and we hope that it will eventually replace the current
8
[`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
this [Haskell Symposium 2016 paper][paper] and this [Haskell eXchange 2016 talk][talk].
11

12 13
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
14
e.g. `inplace/bin/ghc-stage1`.
15

16 17 18 19 20 21 22 23 24 25
Your first build
----------------

Beware, the build system is in the alpha development phase. Things are shaky and often
break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
follow these steps:

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

* This build system is written in Haskell (obviously) and depends on the following Haskell
26
packages, which need to be installed: `ansi-terminal extra mtl quickcheck shake`.
27

28 29
* Get the sources. It is important for the build system to be in the `hadrian` directory
of the GHC source tree:
30 31 32 33

    ```bash
    git clone --recursive git://git.haskell.org/ghc.git
    cd ghc
Andrey Mokhov's avatar
Andrey Mokhov committed
34
    git clone git://github.com/snowleopard/hadrian
35
    ```
36
    
Andrey Mokhov's avatar
Andrey Mokhov committed
37
* Build GHC using `hadrian/build.sh` or `hadrian/build.bat` (on Windows) instead
38 39
of `make`. You might want to enable parallelism with `-j`. We will further refer to the
build script simply as `build`. If you are interested in building in a Cabal sandbox
40
or using Stack, have a look at `build.cabal.sh` and `build.stack.sh` scripts. Also
41 42 43 44
see [instructions for building GHC on Windows using Stack][windows-build]. Note, Hadrian
runs the `boot` and `configure` scripts automatically on the first build, so that you don't
need to. Use `--skip-configure` to suppress this behaviour (see overview of command line
flags below).
45 46 47

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

51
#### Command line flags
52 53 54

In addition to standard Shake flags (try `--help`), the build system
currently supports several others:
55 56 57 58 59
* `--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).
60

Andrey Mokhov's avatar
Andrey Mokhov committed
61
* `--haddock`: build Haddock documentation.
62

63 64 65
* `--integer-simple`: build GHC using the `integer-simple` integer library (instead
of `integer-gmp`).

66 67 68 69 70
* `--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).

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

75 76 77 78 79 80 81 82 83 84
* `--skip-configure`: use this flag to suppress the default behaviour of Hadrian that
runs the `boot` and `configure` scripts automatically if need be, so that you don't have
to remember to run them manually. With `--skip-configure` you will need to manually run:

    ```bash
    ./boot
    ./configure # On Windows run ./configure --enable-tarballs-autodownload
    ```
as you normally do when using `make`. Beware, by default Hadrian may do network I/O on
Windows to download necessary tarballs, which may sometimes be undesirable; `--skip-configure`
85 86
is your friend in such cases.

87 88 89
* `--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
90 91 92
* `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
by Shake oracles.

93
#### User settings
94 95

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

98
#### Clean and full rebuild
99

Andrey Mokhov's avatar
Andrey Mokhov committed
100
* `build clean` removes all build artefacts. 
101

Andrey Mokhov's avatar
Andrey Mokhov committed
102 103
* `build -B` forces Shake to rerun all rules, even if the previous build results are
are still up-to-date.
104 105 106 107

#### Source distribution

To build a GHC source distribution tarball, run Hadrian with the `sdist-ghc` target.
Andrey Mokhov's avatar
Andrey Mokhov committed
108

Zhen Zhang's avatar
Zhen Zhang committed
109 110 111 112
#### Installation

To build and install GHC artifacts, run the `install` target.

113 114 115
By default, the artifacts will be installed to `<prefix>` on your system
(in this case, the `DESTDIR` is empty, corresponds to the root of the file system).
For example on UNIX, `ghc` will be installed to `/usr/local/bin`. By setting flag `--install-destdir=[DESTDIR]`,
Zhen Zhang's avatar
Zhen Zhang committed
116
you can install things to non-system path `DESTDIR/<prefix>` instead.
117 118
Make sure you use correct absolute path on Windows, e.g. `C:/path`,
i.e. GHC is installed into `C:/path/usr/local` for the above example.
Zhen Zhang's avatar
Zhen Zhang committed
119

Andrey Mokhov's avatar
Andrey Mokhov committed
120 121
#### Testing

122 123 124
* `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.
Andrey Mokhov's avatar
Andrey Mokhov committed
125

126 127 128
* `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
129

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

133 134 135
Current limitations
-------------------
The new build system still lacks many important features:
136
* Validation is not implemented: [#187][validation-issue].
Zhen Zhang's avatar
Zhen Zhang committed
137
* Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
Andrey Mokhov's avatar
Andrey Mokhov committed
138
* Only HTML Haddock documentation is supported (use `--haddock` flag). 
139
* Not all modes of the old build system are supported, e.g. [#250][freeze-issue].
140
* Cross-compilation is not implemented: [#177][cross-compilation-issue].
Zhen Zhang's avatar
Zhen Zhang committed
141
* There is no support for binary distribution: [#219][install-issue].
142

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

145 146
How to contribute
-----------------
147 148

The best way to contribute is to try the new build system, report the issues
Andrey Mokhov's avatar
Andrey Mokhov committed
149 150 151
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
152 153
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
154 155
Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
where open issues and pull requests are grouped into categories.
156

157 158 159 160
Acknowledgements
----------------

I started this project as part of my 6-month research visit to Microsoft
Andrey Mokhov's avatar
Andrey Mokhov committed
161
Research Cambridge, which was funded by Newcastle University, EPSRC, and
162
Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
163 164 165 166 167 168
and Simon Marlow for kick-starting the project and for their guidance. 
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.
169 170

[ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
171
[shake]: https://github.com/ndmitchell/shake/blob/master/README.md
172
[make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
173 174
[paper]: https://www.staff.ncl.ac.uk/andrey.mokhov/Hadrian.pdf
[talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
Andrey Mokhov's avatar
Andrey Mokhov committed
175
[issues]: https://github.com/snowleopard/hadrian/issues
176 177
[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
178
[windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
179
[ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
Andrey Mokhov's avatar
Andrey Mokhov committed
180 181
[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
182
[dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
183
[freeze-issue]: https://github.com/snowleopard/hadrian/issues/250
Andrey Mokhov's avatar
Andrey Mokhov committed
184 185 186 187
[cross-compilation-issue]: https://github.com/snowleopard/hadrian/issues/177
[install-issue]: https://github.com/snowleopard/hadrian/issues/219
[milestones]: https://github.com/snowleopard/hadrian/milestones
[contributors]: https://github.com/snowleopard/hadrian/graphs/contributors