testsuite: Assert that testsuite ways are known
[ghc.git] / hadrian / README.md
1 Hadrian
2 =======
3
4 Hadrian is a new build system for the [Glasgow Haskell Compiler][ghc]. It is
5 based on the [Shake][shake] library and we hope that it will replace the current
6 [Make-based build system][make] starting from GHC 8.8. If you are curious about
7 the rationale behind the
8 project and the architecture of the build system you can find more details in
9 this [Haskell Symposium 2016 paper](https://dl.acm.org/authorize?N41275) and this
10 [Haskell eXchange 2016 talk][talk].
11
12 The new build system can work side-by-side with the existing build system, since it
13 places all build artefacts in a dedicated directory (called `_build` by default).
14
15 Your first build
16 ----------------
17
18 Hadrian has not entirely caught up with the Make build system. Not afraid?
19 Then put on the helmet and run the following commands from the root of the GHC
20 tree:
21
22 ```
23 ./boot && ./configure
24 hadrian/build.sh -j
25 ```
26
27 or on Windows:
28
29 ```
30 ./boot && ./configure --enable-tarballs-autodownload
31 hadrian/build.bat -j
32 ```
33
34 Here flag `-j` enables parallelism and is optional. We will further refer to the
35 build script simply as `build`. Note that Hadrian can also run the `boot` and
36 `configure` scripts automatically for you if you pass the flag `--configure`,
37 or simply `-c`. See the overview of command line flags below.
38
39 Notes:
40
41 * If the default build script doesn't work, you might want to try another one,
42 e.g. based on Cabal sandboxes (`build.cabal.*`), Stack (`build.stack.*`) or Nix
43 (`build.stack.nix.*`).
44
45 * On Windows, if you do not want to install MSYS, you can use the Stack-based
46 build script (Stack provides a managed MSYS environment), as described in
47 [these instructions][windows-build]. If you don't mind installing MSYS yourself
48 or already have it, you can use the Cabal-based build script.
49
50 * Hadrian is written in Haskell and depends on `shake` (plus a few packages that
51 `shake` depends on), `mtl`, `quickcheck`, and GHC core libraries.
52
53 * If you have never built GHC before, start with the
54 [preparation guide][ghc-preparation].
55
56 Cheatsheet for Make users
57 -------------------------
58
59 You can find a cheatsheet-style document that shows the Hadrian equivalents of
60 commands that GHC users are used to run with the Make build system
61 [here](doc/make.md).
62
63 Using the build system
64 ----------------------
65 Once your first build is successful, simply run `build` to rebuild after some
66 changes. Build results are placed into `_build` by default.
67
68 #### Command line flags
69
70 In addition to standard Shake flags (try `--help`), the build system
71 currently supports several others:
72
73 * `--build-root=PATH` or `-oPATH`: specify the directory in which you want to
74 store all build products. By default Hadrian builds everything in the `_build/`
75 subdirectory of the GHC source tree. Unlike the Make build system, Hadrian
76 doesn't have any "inplace" logic left any more. This option is therefore useful
77 for GHC developers who want to build GHC in different ways or at different
78 commits, from the same source directory, and have the build products sit in
79 different, isolated folders.
80
81 * `--configure` or `-c`: use this flag to run the `boot` and `configure` scripts
82 automatically, so that you don't have to remember to run them manually as you
83 normally do when using Make (typically only in the first build):
84     ```bash
85     ./boot
86     ./configure # On Windows run ./configure --enable-tarballs-autodownload
87     ```
88     Beware that with this flag Hadrian may do network I/O on Windows to download
89     necessary tarballs, which may sometimes be undesirable.
90
91 * `--flavour=FLAVOUR`: choose a build flavour. The following settings are
92 currently supported: `default`, `quick`, `quickest`, `perf`, `prof`, `devel1`
93 and `devel2`. As an example, the `quickest` flavour adds `-O0` flag to all GHC
94 invocations and builds libraries only in the `vanilla` way, which speeds up
95 builds by 3-4x. Build flavours are documented
96 [here](https://gitlab.haskell.org/ghc/ghc/blob/master/hadrian/doc/flavours.md).
97
98 * `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its
99 source files are out-of-date. This allows to significantly reduce the rebuild
100 time when you are working on a feature that affects both Stage1 and Stage2
101 compilers, but may lead to incorrect build results. To unfreeze Stage1 GHC
102 simply drop the `--freeze1` flag and Hadrian will rebuild all out-of-date files.
103
104 * `--integer-simple`: build GHC using the `integer-simple` integer library
105 (instead of `integer-gmp`).
106
107 * `--color` and `--no-color`: choose whether to use colors when printing build
108 progress info. By default, Hadrian tries to determine if the terminal supports
109 colored ouput, and proceeds accordingly.
110
111 * `--progress-info=STYLE`: choose how build progress info is printed. There are
112 four settings: `none`, `brief` (one line per build command; this is the default
113 setting), `normal` (typically a box per build command), and `unicorn` (when
114 `normal` just won't do).
115
116 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic
117 messages by Shake oracles.
118
119 * `--lint`: run [Shake Lint](https://shakebuild.com/manual#lint) during the
120 build to check that the build system is well formed. Note that the Lint check
121 currently fails under certain circumstances, as discussed in
122 [this ticket](https://gitlab.haskell.org/ghc/ghc/issues/15971).
123
124 #### Expressions
125
126 Hadrian expressions are used extensively for specifying build settings. For an
127 explanation of how they work, see the [documentation](doc/expressions.md).
128
129 #### User settings
130
131 The Make-based build system uses `mk/build.mk` to specify user build settings.
132 Hadrian uses `hadrian/UserSettings.hs` for the same purpose, see
133 [documentation](doc/user-settings.md).
134
135 #### Building libraries and executables
136
137 You can build a specific library or executable for a given stage by running
138 `build stage<N>:<lib|exe>:<package name>`. Examples:
139
140 ```sh
141 # Build the Stage1 GHC compiler, and place the binary to the directory
142 # _build/stage0/bin/ghc (because it is built by the Stage0 compiler).
143 build stage1:exe:ghc-bin
144
145 # Build the Stage2 GHC compiler, and place the binary to the directory
146 # _build/stage1/bin/ghc (because it is built by the Stage1 compiler).
147 build stage2:exe:ghc-bin
148
149 # Build the `ghc` library with the bootstrapping (Stage0) compiler, and register
150 # it in the package database stored in the directory _build/stage0/lib.
151 build stage0:lib:ghc
152
153 # Build the Cabal library with the Stage1 compiler and register it
154 # in the package database stored in the directory _build/stage1/lib.
155
156 # Build the `text` library with the Stage2 compiler and register it
157 # in the package database stored in the directory _build/stage2/lib.
158 build stage2:lib:text
159
160 # Build Haddock using the Stage1 compiler and place the binary into the
161 # directory _build/stage1/haddock.
162 build stage1:exe:haddock
163 ```
164
165 #### Fast feedback using ghci
166
167 Running the `./hadrian/ghci.sh` script will load the main compiler into
168 a ghci session. This is intended for fast development feedback, modules are only
169 typechecked so it isn't possible to run any functions in the repl.
170
171 ```
172 ./hadrian/ghci.sh
173 ```
174
175 You can also use this target with `ghcid`.
176
177 ```
178 ghcid --command="./hadrian/ghci.sh"
179 ```
180
181 The first time this command is run hadrian will need to compile a few dependencies
182 which will take 1-2 minutes. Loading GHC into GHCi itself takes about 30 seconds and
183 reloads after that take in the region of 1-5 seconds depending on which modules
184 need to be recompiled.
185
186 You can further speed up the script by passing `-j` as an argument. This will
187 have the effect of passing `-j` to both hadrian and ghci so they will both
188 build in parallel.
189
190 ```
191 ./hadrian/ghci.sh -j8
192 ```
193
194 #### Testing
195
196 To run GHC testsuite, use `build test`. See
197 [doc/testsuite.md](doc/testsuite.md) to learn about all associated command line
198 flags, as well as about the equivalents of the features that the Make build
199 system offers.
200
201 `build selftest` runs tests of the build system. The current test coverage
202 is close to zero (see [#197][test-issue]).
203
204 #### Clean and full rebuild
205
206 * `build clean` removes all build artefacts.
207
208 * `build -B` forces Shake to rerun all rules, even if the previous build results
209 are still up-to-date.
210
211 #### Staged compilation
212
213 GHC is a self-hosted compiler and consequently the build proceeds in several
214 stages:
215
216 1. The build begins with a user-provided installation of GHC called the
217    stage0 (or bootstrap) compiler which is used (via the `build.*.sh` scripts)
218    to build Hadrian.
219 1. Hadrian uses the stage0 compiler to build a stage1 compiler (somewhat
220    confusingly found in `_build/stage0/bin/ghc`), linking against the stage0
221    compiler's core libraries (e.g. `base`).
222 1. The stage1 compiler is used to build new core libraries (found in
223    `_build/stage1/lib`).
224 1. The stage1 compiler is used to build a stage2 compiler (found in
225    `_build/stage1/bin/ghc`), linking against these new core libraries.
226 1. Optionally (see the [Building Stage3](#building-stage3) section below) the
227    stage2 compiler can be used to build a stage3 compiler (found in
228    `build/stage2/bin/ghc`) as a further smoke-test.
229
230 Note that the stage directories in the `_build` directory can be thought of as
231 named after the stage that was used to *build* the artifacts in each directory.
232
233 These stages can be summarized graphically:
234
235 ![an overview of the stages of a Hadrian compilation](doc/staged-compilation.svg)
236
237 #### Documentation
238
239 To build GHC documentation, run `build docs`. Note that finer-grain
240 documentation targets (e.g. building only HTML documentation or only the GHC
241 User's Guide) are currently not supported.
242
243 #### Source distribution
244
245 To build a GHC source distribution tarball, run `build source-dist`.
246
247 #### Binary distribution
248
249 To build a GHC binary distribution, run `build binary-dist`. The resulting
250 tarball contains just enough to support the
251
252 ``` sh
253 $ ./configure [--prefix=PATH] && make install
254 ```
255
256 workflow, for now.
257
258 #### Building Stage3
259
260 It is possible to define a build flavour that builds a Stage3 compiler, which is
261 a compiler built using Stage2. This is useful for cross-compilation. Detailed
262 instructions can be found in the corresponding
263 [part of the user settings manual](doc/user-settings.md#specifying-the-final-stage-to-build).
264
265 #### Integrating Hadrian into other tooling
266
267 The `tool-args` target is designed to allow hadrian to be integrated into other
268 tooling which uses the GHC API.
269 `tool-args` prints out a list of flags which hadrian will use to compile
270 a module in the `compiler` directory. Using these flags you can then set up
271 a GHC API session with the correct environment to load a module into your own
272 GHC session. This is how `haskell-ide-engine` is able to support hadrian.
273
274 ```
275 > ./hadrian/build.sh tool-args
276 -hide-all-packages -no-user-package-db -package-db _build/stage0/lib/packag...
277 ```
278
279
280 The `./hadrian/ghci.sh` script is implemented using this target.
281
282 Troubleshooting
283 ---------------
284
285 Here are a few simple suggestions that might help you fix the build:
286
287 * If Hadrian fails with the message
288   `Configuration file hadrian/cfg/system.config is missing`, you have probably
289   forgotten to pass the `--configure` flag during the first build.
290
291 * With the `--configure` (`-c`) flag, Hadrian sometimes fetches a wrong
292   Happy saying something like: `HappyTemplate-arrays-coerce: openFile: does not exist`
293   (as mentioned [here](https://github.com/haskell/cabal/issues/5867)), in
294   which case you might be better off running `./configure` manually before Hadrian.
295
296 * The call to `build test` sometimes fails with
297   `libCffi_p.a: copyFile: does not exist` (as noticed
298   [here](https://gitlab.haskell.org/ghc/ghc/issues/15877#note_166739)).
299   The workaround is to `rm _build/stage1/libffi/build/inst/lib/libffi.a` and
300   start over.
301
302 If you need help in debugging Hadrian, read the
303 [wiki](https://github.com/snowleopard/hadrian/wiki)
304 and Shake's [debugging tutorial](https://shakebuild.com/debugging).
305 If nothing helps, don't hesitate to create a GHC issue.
306
307 Current limitations
308 -------------------
309 The new build system still lacks many important features:
310 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
311
312 How to contribute
313 -----------------
314
315 The best way to contribute is to try Hadrian, report the issues you found, and
316 attempt to fix them. Documentation patches are particularly welcome. Please
317 note: the codebase is still unstable and we expect some further refactoring. In
318 particular, we would like to separate the general-purpose "Hadrian library" for
319 building Haskell projects using Shake (`src/Hadrian/*`) from GHC specifics; see
320 [this issue](https://github.com/snowleopard/hadrian/issues/347).
321
322 Acknowledgements
323 ----------------
324
325 The list of people who helped create Hadrian is long, and we hope that it will
326 soon become even longer! The project was first developed in a separate GitHub
327 repository, where you can find the list of original
328 [contributors][contributors]. They had to stare at Makefiles for months, so give
329 them all a round of applause. Simon Peyton Jones and Simon Marlow helped with
330 deciphering these Makefiles, and Neil Mitchell patiently explained how to
331 translate Makefiles to (much nicer) Shakefiles.
332
333 The initial development of Hadrian was funded by Newcastle University, EPSRC and
334 Microsoft Research. Other organisations that contributed at various stages of
335 the project are Haskell.Org and Google (both through supporting summer student
336 projects), as well as Well-Typed.
337
338 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
339 [shake]: https://github.com/ndmitchell/shake
340 [make]: https://gitlab.haskell.org/ghc/ghc/wikis/building/architecture
341 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
342 [issues]: https://github.com/snowleopard/hadrian/issues
343 [ghc-preparation]: https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation
344 [ghc-windows-quick-build]: https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation/windows#AQuickBuild
345 [windows-build]: https://gitlab.haskell.org/ghc/ghc/blob/master/hadrian/doc/windows.md
346 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
347 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
348 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
349 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors