Add an Outputable instance for SDoc with ppr = id.
[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://github.com/snowleopard/hadrian/blob/master/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 * `--progress-colour=MODE`: choose whether to use colours when printing build
108 progress info. There are three settings: `never` (do not use colours), `auto`
109 (attempt to detect whether the console supports colours; this is the default
110 setting), and `always` (use colours).
111
112 * `--progress-info=STYLE`: choose how build progress info is printed. There are
113 four settings: `none`, `brief` (one line per build command; this is the default
114 setting), `normal` (typically a box per build command), and `unicorn` (when
115 `normal` just won't do).
116
117 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic
118 messages by Shake oracles.
119
120 * `--lint`: run [Shake Lint](https://shakebuild.com/manual#lint) during the
121 build to check that the build system is well formed. Note that the Lint check
122 currently fails under certain circumstances, as discussed in
123 [this ticket](https://gitlab.haskell.org/ghc/ghc/issues/15971).
124
125 #### User settings
126
127 The Make-based build system uses `mk/build.mk` to specify user build settings.
128 Hadrian uses `hadrian/UserSettings.hs` for the same purpose, see
129 [documentation](doc/user-settings.md).
130
131 #### Building libraries and executables
132
133 You can build a specific library or executable for a given stage by running
134 `build stage<N>:<lib|exe>:<package name>`. Examples:
135
136 ```sh
137 # Build the Stage1 GHC compiler, and place the binary to the directory
138 # _build/stage0/bin/ghc (because it is built by the Stage0 compiler).
139 build stage1:exe:ghc-bin
140
141 # Build the Stage2 GHC compiler, and place the binary to the directory
142 # _build/stage1/bin/ghc (because it is built by the Stage1 compiler).
143 build stage2:exe:ghc-bin
144
145 # Build the `ghc` library with the bootstrapping (Stage0) compiler, and register
146 # it in the package database stored in the directory _build/stage0/lib.
147 build stage0:lib:ghc
148
149 # Build the Cabal library with the Stage1 compiler and register it
150 # in the package database stored in the directory _build/stage1/lib.
151
152 # Build the `text` library with the Stage2 compiler and register it
153 # in the package database stored in the directory _build/stage2/lib.
154 build stage2:lib:text
155
156 # Build Haddock using the Stage1 compiler and place the binary into the
157 # directory _build/stage1/haddock.
158 build stage1:exe:haddock
159 ```
160
161 #### Fast feedback using ghci
162
163 Running the `./hadrian/ghci.sh` script will load the main compiler into
164 a ghci session. This is intended for fast development feedback, modules are only
165 typechecked so it isn't possible to run any functions in the repl.
166
167 ```
168 ./hadrian/ghci.sh
169 ```
170
171 You can also use this target with `ghcid`.
172
173 ```
174 ghcid --command="./hadrian/ghci.sh"
175 ```
176
177 The first time this command is run hadrian will need to compile a few dependencies
178 which will take 1-2 minutes. Loading GHC into GHCi itself takes about 30 seconds and
179 reloads after that take in the region of 1-5 seconds depending on which modules
180 need to be recompiled.
181
182 #### Testing
183
184 To run GHC testsuite, use `build test`. See
185 [doc/testsuite.md](doc/testsuite.md) to learn about all associated command line
186 flags, as well as about the equivalents of the features that the Make build
187 system offers.
188
189 `build selftest` runs tests of the build system. The current test coverage
190 is close to zero (see [#197][test-issue]).
191
192 #### Clean and full rebuild
193
194 * `build clean` removes all build artefacts.
195
196 * `build -B` forces Shake to rerun all rules, even if the previous build results
197 are still up-to-date.
198
199 #### Documentation
200
201 To build GHC documentation, run `build docs`. Note that finer-grain
202 documentation targets (e.g. building only HTML documentation or only the GHC
203 User's Guide) are currently not supported.
204
205 #### Source distribution
206
207 To build a GHC source distribution tarball, run `build source-dist`.
208
209 #### Binary distribution
210
211 To build a GHC binary distribution, run `build binary-dist`. The resulting
212 tarball contains just enough to support the
213
214 ``` sh
215 $ ./configure [--prefix=PATH] && make install
216 ```
217
218 workflow, for now.
219
220 #### Building Stage3
221
222 It is possible to define a build flavour that builds a Stage3 compiler, which is
223 a compiler built using Stage2. This is useful for cross-compilation. Detailed
224 instructions can be found in the corresponding
225 [part of the user settings manual](doc/user-settings.md#specifying-the-final-stage-to-build).
226
227 #### Integrating Hadrian into other tooling
228
229 The `tool-args` target is designed to allow hadrian to be integrated into other
230 tooling which uses the GHC API.
231 `tool-args` prints out a list of flags which hadrian will use to compile
232 a module in the `compiler` directory. Using these flags you can then set up
233 a GHC API session with the correct environment to load a module into your own
234 GHC session. This is how `haskell-ide-engine` is able to support hadrian.
235
236 ```
237 > ./hadrian/build.sh tool-args
238 -hide-all-packages -no-user-package-db -package-db _build/stage0/lib/packag...
239 ```
240
241
242 The `./hadrian/ghci.sh` script is implemented using this target.
243
244 Troubleshooting
245 ---------------
246
247 Here are a few simple suggestions that might help you fix the build:
248
249 * If Hadrian fails with the message
250   `Configuration file hadrian/cfg/system.config is missing`, you have probably
251   forgotten to pass the `--configure` flag during the first build. 
252
253 * With the `--configure` (`-c`) flag, Hadrian sometimes fetches a wrong 
254   Happy saying something like: `HappyTemplate-arrays-coerce: openFile: does not exist`
255   (as mentioned [here](https://github.com/haskell/cabal/issues/5867)), in 
256   which case you might be better off running `./configure` manually before Hadrian.
257
258 * The call to `build test` sometimes fails with 
259   `libCffi_p.a: copyFile: does not exist` (as noticed 
260   [here](https://gitlab.haskell.org/ghc/ghc/issues/15877#note_166739)). 
261   The workaround is to `rm _build/stage1/libffi/build/inst/lib/libffi.a` and 
262   start over.
263
264 If you need help in debugging Hadrian, read the 
265 [wiki](https://github.com/snowleopard/hadrian/wiki)
266 and Shake's [debugging tutorial](https://shakebuild.com/debugging).
267 If nothing helps, don't hesitate to create a GHC issue.
268
269 Current limitations
270 -------------------
271 The new build system still lacks many important features:
272 * Validation is not implemented: [#187][validation-issue].
273 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
274
275 How to contribute
276 -----------------
277
278 The best way to contribute is to try Hadrian, report the issues you found, and
279 attempt to fix them. Documentation patches are particularly welcome. Please
280 note: the codebase is still unstable and we expect some further refactoring. In
281 particular, we would like to separate the general-purpose "Hadrian library" for
282 building Haskell projects using Shake (`src/Hadrian/*`) from GHC specifics; see
283 [this issue](https://github.com/snowleopard/hadrian/issues/347).
284
285 Acknowledgements
286 ----------------
287
288 The list of people who helped create Hadrian is long, and we hope that it will
289 soon become even longer! The project was first developed in a separate GitHub
290 repository, where you can find the list of original
291 [contributors][contributors]. They had to stare at Makefiles for months, so give
292 them all a round of applause. Simon Peyton Jones and Simon Marlow helped with
293 deciphering these Makefiles, and Neil Mitchell patiently explained how to
294 translate Makefiles to (much nicer) Shakefiles.
295
296 The initial development of Hadrian was funded by Newcastle University, EPSRC and
297 Microsoft Research. Other organisations that contributed at various stages of
298 the project are Haskell.Org and Google (both through supporting summer student
299 projects), as well as Well-Typed.
300
301 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
302 [shake]: https://github.com/ndmitchell/shake
303 [make]: https://gitlab.haskell.org/ghc/ghc/wikis/building/architecture
304 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
305 [issues]: https://github.com/snowleopard/hadrian/issues
306 [ghc-preparation]: https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation
307 [ghc-windows-quick-build]: https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation/windows#AQuickBuild
308 [windows-build]: https://gitlab.haskell.org/ghc/ghc/blob/master/hadrian/doc/windows.md
309 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
310 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
311 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
312 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
313 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors