0684380c23a96179ffc93a2d182b1625d3ccc43d
[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. Note, there is
14 some interaction between them: they put (some) build results in the same directories,
15 e.g. the resulting GHC is `inplace/bin/ghc-stage2`.
16
17 Your first build
18 ----------------
19
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 hadrian/build.sh -j
26 ```
27
28 or on Windows:
29
30 ```
31 hadrian/build.bat -j
32 ```
33
34 Here flag `-j` enables parallelism and is optional. We will further refer to the build script
35 simply as `build`. Note that Hadrian can also run the `boot` and `configure` scripts
36 automatically if you pass the flag `--configure`, or simply `-c`. See the overview of
37 command line flags below.
38
39 Notes:
40
41 * If the default build script doesn't work, you might want to give a try to another one, e.g. based
42 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].
44
45 * Hadrian is written in Haskell and depends on `shake` (plus a few packages that `shake` depends on),
46 `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 Using the build system
51 ----------------------
52 Once your first build is successful, simply run `build` to rebuild. Build results
53 are placed into `_build` and `inplace` directories.
54
55 #### Command line flags
56
57 In addition to standard Shake flags (try `--help`), the build system
58 currently supports several others:
59
60 * `--configure` or `-c`: use this flag to run the `boot` and `configure` scripts
61 automatically, so that you don't have to remember to run them manually as you normally
62 do when using Make (typically only in the first build):
63     ```bash
64     ./boot
65     ./configure # On Windows run ./configure --enable-tarballs-autodownload
66     ```
67     Beware that with this flag Hadrian may do network I/O on Windows to download necessary
68     tarballs, which may sometimes be undesirable.
69
70 * `--flavour=FLAVOUR`: choose a build flavour. The following settings are currently supported:
71 `default`, `quick`, `quickest`, `perf`, `prof`, `devel1` and `devel2`. As an example, the
72 `quickest` flavour adds `-O0` flag to all GHC invocations and builds libraries only in the
73 `vanilla` way, which speeds up builds by 3-4x. Build flavours are documented
74 [here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md).
75
76 * `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its source files
77 are out-of-date. This allows to significantly reduce the rebuild time when you are working
78 on a feature that affects both Stage1 and Stage2 compilers, but may lead to incorrect
79 build results. To unfreeze Stage1 GHC simply drop the `--freeze1` flag and Hadrian will
80 rebuild all out-of-date files.
81
82 * `--integer-simple`: build GHC using the `integer-simple` integer library (instead
83 of `integer-gmp`).
84
85 * `--progress-colour=MODE`: choose whether to use colours when printing build progress
86 info. There are three settings: `never` (do not use colours), `auto` (attempt to detect
87 whether the console supports colours; this is the default setting), and `always` (use
88 colours).
89
90 * `--progress-info=STYLE`: choose how build progress info is printed. There are four
91 settings: `none`, `brief` (one line per build command; this is the default setting),
92 `normal` (typically a box per build command), and `unicorn` (when `normal` just won't do).
93
94 * `--split-objects`: generate split objects, which are switched off by default. Due to
95 a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.
96
97 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
98 by Shake oracles.
99
100 #### User settings
101
102 The Make-based build system uses `mk/build.mk` to specify user build settings. We
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
109 * `build -B` forces Shake to rerun all rules, even if the previous build results are
110 are still up-to-date.
111
112 #### Documentation
113
114 To build GHC documentation, run `build docs`. Note that finer-grain documentation
115 targets (e.g. building only HTML documentation or only the GHC User's Guide)
116 are currently not supported.
117
118 #### Source distribution
119
120 To build a GHC source distribution tarball, run `build sdist-ghc`.
121
122 #### Installation
123
124 To build and install GHC artifacts, run `build install`.
125
126 By default, GHC will be installed to the specified _prefix_ path on your system,
127 relative to the root of the file system. For example on UNIX, GHC will be installed
128 to `/usr/local/bin`. By setting the command line flag `--install-destdir=[DESTDIR]`,
129 you can install GHC to path `DESTDIR/<prefix>` instead. Make sure you use correct
130 absolute path as `DESTDIR` on Windows, e.g. `C:/path`, which installs GHC
131 into `C:/path/usr/local`.
132
133 #### Testing
134
135 * `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
136 directory. This can be used instead of `sh validate --fast --no-clean` in the existing
137 build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
138
139 * `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
140 script with appropriate flags. The current implementation is limited and cannot
141 replace the `validate` script (see [#187][validation-issue]).
142
143 * `build selftest` runs tests of the build system. Current test coverage is close to
144 zero (see [#197][test-issue]).
145
146 Current limitations
147 -------------------
148 The new build system still lacks many important features:
149 * Validation is not implemented: [#187][validation-issue].
150 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
151 * There is no support for binary distribution: [#219][bin-dist-issue].
152
153 Check out [milestones] to see when we hope to resolve the above limitations.
154
155 How to contribute
156 -----------------
157
158 The best way to contribute is to try the new build system, report the issues
159 you found, and attempt to fix them. Please note: the codebase is very unstable
160 at present and we expect a lot of further refactoring. If you would like to
161 work on a particular issue, please let everyone know by adding a comment about
162 this. The issues that are currently on the critical path and therefore require
163 particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239).
164 Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
165 where open issues and pull requests are grouped into categories.
166
167 Acknowledgements
168 ----------------
169
170 I started this project as part of my 6-month research visit to Microsoft
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 Zhen Zhang has done fantastic work on Hadrian as part of his Summer of
175 Haskell 2017 [project](https://summer.haskell.org/ideas.html#hadrian-ghc),
176 solving a few heavy and long-overdue issues. Last but not least, big thanks
177 to all other project [contributors][contributors], who helped me endure and
178 enjoy the project.
179
180 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
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
184 [issues]: https://github.com/snowleopard/hadrian/issues
185 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
186 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
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
189 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
190 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
191 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
192 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
193 [milestones]: https://github.com/snowleopard/hadrian/milestones
194 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors