Remove ghctags (#16274)
[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 * `--split-objects`: generate split objects, which are switched off by default.
118 Due to a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using
119 this flag.
120
121 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic
122 messages by Shake oracles.
123
124 * `--lint`: run [Shake Lint](https://shakebuild.com/manual#lint) during the
125 build to check that the build system is well formed. Note that the Lint check
126 currently fails under certain circumstances, as discussed in
127 [this ticket](https://ghc.haskell.org/trac/ghc/ticket/15971).
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 #### Testing
166
167 To run GHC testsuite, use `build test`. See
168 [doc/testsuite.md](doc/testsuite.md) to learn about all associated command line
169 flags, as well as about the equivalents of the features that the Make build
170 system offers.
171
172 `build selftest` runs tests of the build system. The current test coverage
173 is close to zero (see [#197][test-issue]).
174
175 #### Clean and full rebuild
176
177 * `build clean` removes all build artefacts.
178
179 * `build -B` forces Shake to rerun all rules, even if the previous build results
180 are still up-to-date.
181
182 #### Documentation
183
184 To build GHC documentation, run `build docs`. Note that finer-grain
185 documentation targets (e.g. building only HTML documentation or only the GHC
186 User's Guide) are currently not supported.
187
188 #### Source distribution
189
190 To build a GHC source distribution tarball, run `build source-dist`.
191
192 #### Binary distribution
193
194 To build a GHC binary distribution, run `build binary-dist`. The resulting
195 tarball contains just enough to support the
196
197 ``` sh
198 $ ./configure [--prefix=PATH] && make install
199 ```
200
201 workflow, for now.
202
203 #### Building Stage3
204
205 It is possible to define a build flavour that builds a Stage3 compiler, which is
206 a compiler built using Stage2. This is useful for cross-compilation. Detailed
207 instructions can be found in the corresponding
208 [part of the user settings manual](doc/user-settings.md#specifying-the-final-stage-to-build).
209
210 Troubleshooting
211 ---------------
212
213 Here are a few simple suggestions that might help you fix the build:
214
215 * If Hadrian fails with the message
216   `Configuration file hadrian/cfg/system.config is missing`, you have probably
217   forgotten to pass the `--configure` flag during the first build.
218
219 * If you need help in debugging Hadrian, read the
220   [wiki](https://github.com/snowleopard/hadrian/wiki)
221   and Shake's [debugging tutorial](https://shakebuild.com/debugging).
222
223 If nothing helps, don't hesitate to create a GHC Trac ticket, choosing the
224 component `Build System (Hadrian)`.
225
226 Current limitations
227 -------------------
228 The new build system still lacks many important features:
229 * Validation is not implemented: [#187][validation-issue].
230 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
231
232 How to contribute
233 -----------------
234
235 The best way to contribute is to try Hadrian, report the issues you found, and
236 attempt to fix them. Documentation patches are particularly welcome. Please
237 note: the codebase is still unstable and we expect some further refactoring. In
238 particular, we would like to separate the general-purpose "Hadrian library" for
239 building Haskell projects using Shake (`src/Hadrian/*`) from GHC specifics; see
240 [this issue](https://github.com/snowleopard/hadrian/issues/347).
241
242 Acknowledgements
243 ----------------
244
245 The list of people who helped create Hadrian is long, and we hope that it will
246 soon become even longer! The project was first developed in a separate GitHub
247 repository, where you can find the list of original
248 [contributors][contributors]. They had to stare at Makefiles for months, so give
249 them all a round of applause. Simon Peyton Jones and Simon Marlow helped with
250 deciphering these Makefiles, and Neil Mitchell patiently explained how to
251 translate Makefiles to (much nicer) Shakefiles.
252
253 The initial development of Hadrian was funded by Newcastle University, EPSRC and
254 Microsoft Research. Other organisations that contributed at various stages of
255 the project are Haskell.Org and Google (both through supporting summer student
256 projects), as well as Well-Typed.
257
258 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
259 [shake]: https://github.com/ndmitchell/shake
260 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
261 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
262 [issues]: https://github.com/snowleopard/hadrian/issues
263 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
264 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
265 [windows-build]: https://gitlab.haskell.org/ghc/ghc/blob/master/hadrian/doc/windows.md
266 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
267 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
268 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
269 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
270 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
271 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors