Merge pull request #521 from snowleopard/drop-chmod
[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 `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 Troubleshooting
147 ---------------
148
149 Here are a few simple suggestions that might help you fix the build:
150
151 * The Hadrian submodule in GHC is occasionally behind the master branch of this repository,
152   which contains most recent bug fixes. To switch to the most recent version of Hadrian,
153   run `git pull https://github.com/snowleopard/hadrian.git`. Beware: the most recent version
154   contains the most recent bugs too! If this works, please raise an issue and we will try to
155   push the changes to the GHC submodule as soon as possible.
156   
157 * Hadrian is occasionally broken by changes in GHC. If this happens, you might want to switch
158   to an earlier GHC commit.
159   
160 * If Hadrian fails with the message `Configuration file hadrian/cfg/system.config is missing`,
161   you have probably forgotten to pass the `--configure` flag during the first build.
162   
163 * If you need help in debugging Hadrian, read the [wiki](https://github.com/snowleopard/hadrian/wiki)
164   and Shake's [debugging tutorial](https://shakebuild.com/debugging).
165
166 If everything fails, don't hesitate to [raise an issue](https://github.com/snowleopard/hadrian/issues/new).
167
168 Current limitations
169 -------------------
170 The new build system still lacks many important features:
171 * Validation is not implemented: [#187][validation-issue].
172 * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
173 * There is no support for binary distribution: [#219][bin-dist-issue].
174
175 Check out [milestones] to see when we hope to resolve the above limitations.
176
177 How to contribute
178 -----------------
179
180 The best way to contribute is to try the new build system, report the issues
181 you found, and attempt to fix them. Please note: the codebase is very unstable
182 at present and we expect a lot of further refactoring. If you would like to
183 work on a particular issue, please let everyone know by adding a comment about
184 this. The issues that are currently on the critical path and therefore require
185 particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239).
186 Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
187 where open issues and pull requests are grouped into categories.
188
189 Acknowledgements
190 ----------------
191
192 I started this project as part of my 6-month research visit to Microsoft
193 Research Cambridge, which was funded by Newcastle University, EPSRC, and
194 Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
195 and Simon Marlow for kick-starting the project and for their guidance.
196 Zhen Zhang has done fantastic work on Hadrian as part of his Summer of
197 Haskell 2017 [project](https://summer.haskell.org/ideas.html#hadrian-ghc),
198 solving a few heavy and long-overdue issues. Last but not least, big thanks
199 to all other project [contributors][contributors], who helped me endure and
200 enjoy the project.
201
202 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
203 [shake]: https://github.com/ndmitchell/shake
204 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
205 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
206 [issues]: https://github.com/snowleopard/hadrian/issues
207 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
208 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
209 [windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
210 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
211 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
212 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
213 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
214 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
215 [milestones]: https://github.com/snowleopard/hadrian/milestones
216 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors