Update README.md (#578)
[hadrian.git] / README.md
1 Hadrian
2 =======
3
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)
5
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 soon 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](https://dl.acm.org/authorize?N41275) and this
11 [Haskell eXchange 2016 talk][talk].
12
13 The new build system can work side-by-side with the existing build system, since it
14 places all build artefacts under a dedicated directory. The only thing they both share
15 is the need to run the `./boot` and `./configure` scripts, even though Hadrian can do it
16 for you (see the documentation for the `-c` flag below).
17
18 Your first build
19 ----------------
20
21 Beware, the build system is in the alpha development phase. Things are shaky and sometimes
22 break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
23 run the following command from root of the GHC tree:
24
25 ```
26 hadrian/build.sh -j
27 ```
28
29 or on Windows:
30
31 ```
32 hadrian/build.bat -j
33 ```
34
35 Here flag `-j` enables parallelism and is optional. We will further refer to the build script
36 simply as `build`. Note that Hadrian can also run the `boot` and `configure` scripts
37 automatically if you pass the flag `--configure`, or simply `-c`. See the overview of
38 command line flags below.
39
40 Notes:
41
42 * If the default build script doesn't work, you might want to give a try to another one, e.g. based
43 on Cabal sandboxes (`build.cabal.*`), Stack (`build.stack.*`) or the global package database
44 (`build.global-db.*`). Also see [instructions for building GHC on Windows using Stack][windows-build].
45
46 * Hadrian is written in Haskell and depends on `shake` (plus a few packages that `shake` depends on),
47 `mtl`, `quickcheck`, and GHC core libraries.
48
49 * If you have never built GHC before, start with the [preparation guide][ghc-preparation].
50
51 Using the build system
52 ----------------------
53 Once your first build is successful, simply run `build` to rebuild. Build results
54 are placed into `_build` and `inplace` directories.
55
56 #### Command line flags
57
58 In addition to standard Shake flags (try `--help`), the build system
59 currently supports several others:
60
61 * `--build-root=PATH` or `-oPATH`: specify the directory in which you want to store all
62 the build artifacts. If none is specified by the user, hadrian will store everything
63 under `_build/` at the top of ghc's source tree. Unlike GHC's make build system,
64 hadrian doesn't have any "inplace" logic left anymore. This option is therefore
65 useful for GHC developers who want to build GHC in different ways or at different
66 commits, from the same directory, and have the build products sit in different,
67 isolated folders.
68
69 * `--configure` or `-c`: use this flag to run the `boot` and `configure` scripts
70 automatically, so that you don't have to remember to run them manually as you normally
71 do when using Make (typically only in the first build):
72     ```bash
73     ./boot
74     ./configure # On Windows run ./configure --enable-tarballs-autodownload
75     ```
76     Beware that with this flag Hadrian may do network I/O on Windows to download necessary
77     tarballs, which may sometimes be undesirable.
78
79 * `--flavour=FLAVOUR`: choose a build flavour. The following settings are currently supported:
80 `default`, `quick`, `quickest`, `perf`, `prof`, `devel1` and `devel2`. As an example, the
81 `quickest` flavour adds `-O0` flag to all GHC invocations and builds libraries only in the
82 `vanilla` way, which speeds up builds by 3-4x. Build flavours are documented
83 [here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md).
84
85 * `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its source files
86 are out-of-date. This allows to significantly reduce the rebuild time when you are working
87 on a feature that affects both Stage1 and Stage2 compilers, but may lead to incorrect
88 build results. To unfreeze Stage1 GHC simply drop the `--freeze1` flag and Hadrian will
89 rebuild all out-of-date files.
90
91 * `--integer-simple`: build GHC using the `integer-simple` integer library (instead
92 of `integer-gmp`).
93
94 * `--progress-colour=MODE`: choose whether to use colours when printing build progress
95 info. There are three settings: `never` (do not use colours), `auto` (attempt to detect
96 whether the console supports colours; this is the default setting), and `always` (use
97 colours).
98
99 * `--progress-info=STYLE`: choose how build progress info is printed. There are four
100 settings: `none`, `brief` (one line per build command; this is the default setting),
101 `normal` (typically a box per build command), and `unicorn` (when `normal` just won't do).
102
103 * `--split-objects`: generate split objects, which are switched off by default. Due to
104 a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.
105
106 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
107 by Shake oracles.
108
109 #### User settings
110
111 The Make-based build system uses `mk/build.mk` to specify user build settings. We
112 use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user-settings.md).
113
114 #### Clean and full rebuild
115
116 * `build clean` removes all build artefacts.
117
118 * `build -B` forces Shake to rerun all rules, even if the previous build results are
119 are still up-to-date.
120
121 #### Documentation
122
123 To build GHC documentation, run `build docs`. Note that finer-grain documentation
124 targets (e.g. building only HTML documentation or only the GHC User's Guide)
125 are currently not supported.
126
127 #### Source distribution
128
129 To build a GHC source distribution tarball, run `build source-dist`.
130
131 #### Binary distribution
132
133 To build a GHC binary distribution, run `build binary-dist`. The resulting
134 tarball contains just enough to support the
135
136 ``` sh
137 $ ./configure [--prefix=PATH] && make install
138 ```
139
140 workflow, for now.
141
142 #### Testing
143
144 * `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
145 directory. This can be used instead of `sh validate --fast --no-clean` in the existing
146 build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
147
148 * `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
149 script with appropriate flags. The current implementation is limited and cannot
150 replace the `validate` script (see [#187][validation-issue]).
151
152 * `build selftest` runs tests of the build system. Current test coverage is close to
153 zero (see [#197][test-issue]).
154
155 Troubleshooting
156 ---------------
157
158 Here are a few simple suggestions that might help you fix the build:
159
160 * The Hadrian submodule in GHC is occasionally behind the master branch of this repository,
161   which contains most recent bug fixes. To switch to the most recent version of Hadrian,
162   run `git pull https://github.com/snowleopard/hadrian.git`. Beware: the most recent version
163   contains the most recent bugs too! If this works, please raise an issue and we will try to
164   push the changes to the GHC submodule as soon as possible.
165   
166 * Hadrian is occasionally broken by changes in GHC. If this happens, you might want to switch
167   to an earlier GHC commit.
168   
169 * If Hadrian fails with the message `Configuration file hadrian/cfg/system.config is missing`,
170   you have probably forgotten to pass the `--configure` flag during the first build.
171   
172 * If you need help in debugging Hadrian, read the [wiki](https://github.com/snowleopard/hadrian/wiki)
173   and Shake's [debugging tutorial](https://shakebuild.com/debugging).
174
175 If everything fails, don't hesitate to [raise an issue](https://github.com/snowleopard/hadrian/issues/new).
176
177 Current limitations
178 -------------------
179 The new build system still lacks many important features:
180 * Validation is not implemented: [#187][validation-issue].
181 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
182 * There is no support for binary distribution: [#219][bin-dist-issue].
183
184 Check out [milestones] to see when we hope to resolve the above limitations.
185
186 How to contribute
187 -----------------
188
189 The best way to contribute is to try the new build system, report the issues
190 you found, and attempt to fix them. Please note: the codebase is very unstable
191 at present and we expect a lot of further refactoring. If you would like to
192 work on a particular issue, please let everyone know by adding a comment about
193 this. The issues that are currently on the critical path and therefore require
194 particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239).
195 Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
196 where open issues and pull requests are grouped into categories.
197
198 Acknowledgements
199 ----------------
200
201 I started this project as part of my 6-month research visit to Microsoft
202 Research Cambridge, which was funded by Newcastle University, EPSRC, and
203 Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
204 and Simon Marlow for kick-starting the project and for their guidance.
205 Zhen Zhang has done fantastic work on Hadrian as part of his Summer of
206 Haskell 2017 [project](https://summer.haskell.org/ideas.html#hadrian-ghc),
207 solving a few heavy and long-overdue issues. Last but not least, big thanks
208 to all other project [contributors][contributors], who helped me endure and
209 enjoy the project.
210
211 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
212 [shake]: https://github.com/ndmitchell/shake
213 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
214 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
215 [issues]: https://github.com/snowleopard/hadrian/issues
216 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
217 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
218 [windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
219 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
220 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
221 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
222 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
223 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
224 [milestones]: https://github.com/snowleopard/hadrian/milestones
225 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors