Clarify when to follow the instructions in doc/windows.md.
[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 See [this guide](https://ghc.haskell.org/trac/ghc/wiki/Building/Hadrian/QuickStart)
15 if you'd like to start using Hadrian for building GHC.
16
17 Your first build
18 ----------------
19
20 Hadrian has not entirely caught up with the Make build system. Not afraid?
21 Then put on the helmet and run the following commands from the root of the GHC
22 tree:
23
24 ```
25 ./boot && ./configure
26 hadrian/build.sh -j
27 ```
28
29 or on Windows:
30
31 ```
32 ./boot && ./configure --enable-tarballs-autodownload
33 hadrian/build.bat -j
34 ```
35
36 Here flag `-j` enables parallelism and is optional. We will further refer to the
37 build script simply as `build`. Note that Hadrian can also run the `boot` and
38 `configure` scripts automatically for you if you pass the flag `--configure`,
39 or simply `-c`. See the overview of command line flags below.
40
41 Notes:
42
43 * If the default build script doesn't work, you might want to try another one,
44 e.g. based on Cabal sandboxes (`build.cabal.*`), Stack (`build.stack.*`) or Nix
45 (`build.stack.nix.*`).
46
47 * On Windows, if you do not want to install MSYS, you can use the Stack-based
48 build script (Stack provides a managed MSYS environment), as described in
49 [these instructions][windows-build]. If you don't mind installing MSYS yourself
50 or already have it, you can use the Cabal-based build script.
51
52 * Hadrian is written in Haskell and depends on `shake` (plus a few packages that
53 `shake` depends on), `mtl`, `quickcheck`, and GHC core libraries.
54
55 * If you have never built GHC before, start with the
56 [preparation guide][ghc-preparation].
57
58 Using the build system
59 ----------------------
60 Once your first build is successful, simply run `build` to rebuild after some
61 changes. Build results are placed into `_build` by default.
62
63 #### Command line flags
64
65 In addition to standard Shake flags (try `--help`), the build system
66 currently supports several others:
67
68 * `--build-root=PATH` or `-oPATH`: specify the directory in which you want to
69 store all build products. By default Hadrian builds everything in the `_build/`
70 subdirectory of the GHC source tree. Unlike the Make build system, Hadrian
71 doesn't have any "inplace" logic left any more. This option is therefore useful
72 for GHC developers who want to build GHC in different ways or at different
73 commits, from the same source directory, and have the build products sit in
74 different, isolated folders.
75
76 * `--configure` or `-c`: use this flag to run the `boot` and `configure` scripts
77 automatically, so that you don't have to remember to run them manually as you
78 normally do when using Make (typically only in the first build):
79     ```bash
80     ./boot
81     ./configure # On Windows run ./configure --enable-tarballs-autodownload
82     ```
83     Beware that with this flag Hadrian may do network I/O on Windows to download
84     necessary tarballs, which may sometimes be undesirable.
85
86 * `--flavour=FLAVOUR`: choose a build flavour. The following settings are
87 currently supported: `default`, `quick`, `quickest`, `perf`, `prof`, `devel1`
88 and `devel2`. As an example, the `quickest` flavour adds `-O0` flag to all GHC
89 invocations and builds libraries only in the `vanilla` way, which speeds up
90 builds by 3-4x. Build flavours are documented
91 [here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md).
92
93 * `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its
94 source files are out-of-date. This allows to significantly reduce the rebuild
95 time when you are working on a feature that affects both Stage1 and Stage2
96 compilers, but may lead to incorrect build results. To unfreeze Stage1 GHC
97 simply drop the `--freeze1` flag and Hadrian will rebuild all out-of-date files.
98
99 * `--integer-simple`: build GHC using the `integer-simple` integer library
100 (instead of `integer-gmp`).
101
102 * `--progress-colour=MODE`: choose whether to use colours when printing build
103 progress info. There are three settings: `never` (do not use colours), `auto`
104 (attempt to detect whether the console supports colours; this is the default
105 setting), and `always` (use colours).
106
107 * `--progress-info=STYLE`: choose how build progress info is printed. There are
108 four settings: `none`, `brief` (one line per build command; this is the default
109 setting), `normal` (typically a box per build command), and `unicorn` (when
110 `normal` just won't do).
111
112 * `--split-objects`: generate split objects, which are switched off by default.
113 Due to a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using
114 this flag.
115
116 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic
117 messages by Shake oracles.
118
119 #### User settings
120
121 The Make-based build system uses `mk/build.mk` to specify user build settings.
122 Hadrian uses `hadrian/UserSettings.hs` for the same purpose, see
123 [documentation](doc/user-settings.md).
124
125 #### Building libraries and executables
126
127 You can build a specific library or executable for a given stage by running
128 `build stage<N>:<lib|exe>:<package name>`. Examples:
129
130 ```sh
131 # Build the Stage1 GHC compiler, and place the binary to the directory
132 # _build/stage0/bin/ghc (because it is built by the Stage0 compiler).
133 build stage1:exe:ghc-bin
134
135 # Build the Stage2 GHC compiler, and place the binary to the directory
136 # _build/stage1/bin/ghc (because it is built by the Stage1 compiler).
137 build stage2:exe:ghc-bin
138
139 # Build the `ghc` library with the bootstrapping (Stage0) compiler, and register
140 # it in the package database stored in the directory _build/stage0/lib.
141 build stage0:lib:ghc
142
143 # Build the Cabal library with the Stage1 compiler and register it
144 # in the package database stored in the directory _build/stage1/lib.
145
146 # Build the `text` library with the Stage2 compiler and register it
147 # in the package database stored in the directory _build/stage2/lib.
148 build stage2:lib:text
149
150 # Build Haddock using the Stage1 compiler and place the binary into the
151 # directory _build/stage1/haddock.
152 build stage1:exe:haddock
153 ```
154
155 #### Testing
156
157 To run GHC testsuite, use `build test`. See
158 [doc/testsuite.md](doc/testsuite.md) to learn about all associated command line
159 flags, as well as about the equivalents of the features that the Make build
160 system offers.
161
162 `build selftest` runs tests of the build system. The current test coverage
163 is close to zero (see [#197][test-issue]).
164
165 #### Clean and full rebuild
166
167 * `build clean` removes all build artefacts.
168
169 * `build -B` forces Shake to rerun all rules, even if the previous build results
170 are still up-to-date.
171
172 #### Documentation
173
174 To build GHC documentation, run `build docs`. Note that finer-grain
175 documentation targets (e.g. building only HTML documentation or only the GHC
176 User's Guide) are currently not supported.
177
178 #### Source distribution
179
180 To build a GHC source distribution tarball, run `build source-dist`.
181
182 #### Binary distribution
183
184 To build a GHC binary distribution, run `build binary-dist`. The resulting
185 tarball contains just enough to support the
186
187 ``` sh
188 $ ./configure [--prefix=PATH] && make install
189 ```
190
191 workflow, for now.
192
193 #### Building Stage3
194
195 It is possible to define a build flavour that builds a Stage3 compiler, which is
196 a compiler built using Stage2. This is useful for cross-compilation. Detailed
197 instructions can be found in the corresponding
198 [part of the user settings manual](doc/user-settings.md#specifying-the-final-stage-to-build).
199
200 Troubleshooting
201 ---------------
202
203 Here are a few simple suggestions that might help you fix the build:
204
205 * If Hadrian fails with the message
206   `Configuration file hadrian/cfg/system.config is missing`, you have probably
207   forgotten to pass the `--configure` flag during the first build.
208
209 * If you need help in debugging Hadrian, read the
210   [wiki](https://github.com/snowleopard/hadrian/wiki)
211   and Shake's [debugging tutorial](https://shakebuild.com/debugging).
212
213 If nothing helps, don't hesitate to create a GHC Trac ticket, choosing the
214 component `Build System (Hadrian)`.
215
216 Current limitations
217 -------------------
218 The new build system still lacks many important features:
219 * Validation is not implemented: [#187][validation-issue].
220 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
221
222 How to contribute
223 -----------------
224
225 The best way to contribute is to try Hadrian, report the issues you found, and
226 attempt to fix them. Documentation patches are particularly welcome. Please
227 note: the codebase is still unstable and we expect some further refactoring. In
228 particular, we would like to separate the general-purpose "Hadrian library" for
229 building Haskell projects using Shake (`src/Hadrian/*`) from GHC specifics; see
230 [this issue](https://github.com/snowleopard/hadrian/issues/347).
231
232 Acknowledgements
233 ----------------
234
235 The list of people who helped create Hadrian is long, and we hope that it will
236 soon become even longer! The project was first developed in a separate GitHub
237 repository, where you can find the list of original
238 [contributors][contributors]. They had to stare at Makefiles for months, so give
239 them all a round of applause. Simon Peyton Jones and Simon Marlow helped with
240 deciphering these Makefiles, and Neil Mitchell patiently explained how to
241 translate Makefiles to (much nicer) Shakefiles.
242
243 The initial development of Hadrian was funded by Newcastle University, EPSRC and
244 Microsoft Research. Other organisations that contributed at various stages of
245 the project are Haskell.Org and Google (both through supporting summer student
246 projects), as well as Well-Typed.
247
248 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
249 [shake]: https://github.com/ndmitchell/shake
250 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
251 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
252 [issues]: https://github.com/snowleopard/hadrian/issues
253 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
254 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
255 [windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
256 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
257 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
258 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
259 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
260 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
261 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors