Minor revision
[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)
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 eventually 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 new build system you can find more details in
10 this [Haskell Symposium 2016 paper][paper] and this [Haskell eXchange 2016 talk][talk].
11
12 The new build system can work side-by-side with the existing build system. Note, there is
13 some interaction between them: they put (some) build results in the same directories,
14 e.g. `inplace/bin/ghc-stage1`.
15
16 Your first build
17 ----------------
18
19 Beware, the build system is in the alpha development phase. Things are shaky and often
20 break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
21 follow these steps:
22
23 * If you have never built GHC before, start with the [preparation guide][ghc-preparation].
24
25 * This build system is written in Haskell (obviously) and depends on the following Haskell
26 packages, which need to be installed: `ansi-terminal mtl shake quickcheck`.
27
28 * Get the sources. It is important for the build system to be in the `hadrian` directory
29 of the GHC source tree:
30
31     ```bash
32     git clone --recursive git://git.haskell.org/ghc.git
33     cd ghc
34     git clone git://github.com/snowleopard/hadrian
35     ```
36     
37 * Build GHC using `hadrian/build.sh` or `hadrian/build.bat` (on Windows) instead
38 of `make`. You might want to enable parallelism with `-j`. We will further refer to the
39 build script simply as `build`. If you are interested in building in a Cabal sandbox
40 or using Stack, have a look at `build.cabal.sh` and `build.stack.sh` scripts. Also
41 see [instructions for building GHC on Windows using Stack][windows-build]. Note, Hadrian
42 runs the `boot` and `configure` scripts automatically on the first build, so that you don't
43 need to. Use `--skip-configure` to suppress this behaviour (see overview of command line
44 flags below).
45
46 * Also note on OS X newer versions of XCode ship with a broken `nm` tool
47 ([#11744](https://ghc.haskell.org/trac/ghc/ticket/11744)). One way to mitigate the
48 problem is to add the following into your `UserSettings.hs`:
49   ````haskell
50   userArgs :: Args
51   userArgs = builder (Configure ".") ? arg "--with-nm=$(xcrun --find nm-classic)"
52   ````
53
54 Using the build system
55 ----------------------
56 Once your first build is successful, simply run `build` to rebuild. Most build artefacts
57 are placed into `_build` and `inplace` directories ([#113][build-artefacts-issue]).
58
59 #### Command line flags
60
61 In addition to standard Shake flags (try `--help`), the build system
62 currently supports several others:
63 * `--flavour=FLAVOUR`: choose a build flavour. Two settings are currently supported:
64 `default` and `quick` (adds `-O0` flag to all GHC invocations and disables library
65 profiling, which speeds up builds by 3-4x).
66
67 * `--haddock`: build Haddock documentation.
68
69 * `--progress-colour=MODE`: choose whether to use colours when printing build progress
70 info. There are three settings: `never` (do not use colours), `auto` (attempt to detect
71 whether the console supports colours; this is the default setting), and `always` (use
72 colours).
73
74 * `--progress-info=STYLE`: choose how build progress info is printed. There are four
75 settings: `none`, `brief` (one line per build command), `normal` (typically a box per
76 build command; this is the default setting), and `unicorn` (when `normal` just won't do).
77
78 * `--skip-configure`: use this flag to suppress the default behaviour of Hadrian that
79 runs the `boot` and `configure` scripts automatically if need be, so that you don't have
80 to remember to run them manually. With `--skip-configure` you will need to manually run:
81
82     ```bash
83     ./boot
84     ./configure # On Windows run ./configure --enable-tarballs-autodownload
85     ```
86 as you normally do when using `make`. Beware, by default Hadrian may do network I/O on
87 Windows to download necessary tarballs, which may sometimes be undesirable; `--skip-configure`
88 is your friend in such cases.
89
90 * `--split-objects`: generate split objects, which are switched off by default. Due to
91 a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.
92
93 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
94 by Shake oracles.
95
96 #### User settings
97
98 The `make`-based build system uses `mk/build.mk` to specify user build settings. We
99 use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user-settings.md).
100
101 #### Clean and full rebuild
102
103 * `build clean` removes all build artefacts. Note, we are working towards a
104 complete separation of GHC sources and build artefacts: [#113][build-artefacts-issue].
105
106 * `build -B` forces Shake to rerun all rules, even if results of the previous build
107 are still in the GHC tree. 
108
109 #### Testing
110
111 * `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
112 directory. This can be used instead of `sh validate --fast --no-clean` in the existing
113 build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
114
115 * `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
116 script with appropriate flags. The current implementation is limited and cannot
117 replace the `validate` script (see [#187][validation-issue]).
118
119 * `build selftest` runs tests of the build system. Current test coverage is close to
120 zero (see [#197][test-issue]).
121
122 Current limitations
123 -------------------
124 The new build system still lacks many important features:
125 * We only build `vanilla` and `profiling` way: [#4][dynamic-issue].
126 * Validation is not implemented: [#187][validation-issue].
127 * Only HTML Haddock documentation is supported (use `--haddock` flag). 
128 * Build flavours and conventional command line flags are not implemented: [#188][flavours-issue].
129 * Cross-compilation is not implemented: [#177][cross-compilation-issue].
130 * There is no support for installation or binary/source distribution: [#219][install-issue].
131
132 Check out [milestones] to see when we hope to resolve the above limitations.
133
134 How to contribute
135 -----------------
136
137 The best way to contribute is to try the new build system, report the issues
138 you found, and attempt to fix them. Please note: the codebase is very unstable
139 at present and we expect a lot of further refactoring. If you would like to
140 work on a particular issue, please let everyone know by adding a comment about
141 this. The issues that are currently on the critical path and therefore require
142 particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239).
143
144 Acknowledgements
145 ----------------
146
147 I started this project as part of my 6-month research visit to Microsoft
148 Research Cambridge, which was funded by Newcastle University, EPSRC, and
149 Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
150 and Simon Marlow for kick-starting the project and for their guidance. Last
151 but not least, big thanks to the project [contributors][contributors], who
152 helped me endure and enjoy the project.
153
154 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
155 [shake]: https://github.com/ndmitchell/shake/blob/master/README.md
156 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
157 [paper]: https://www.staff.ncl.ac.uk/andrey.mokhov/Hadrian.pdf
158 [talk]: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc
159 [issues]: https://github.com/snowleopard/hadrian/issues
160 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
161 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
162 [windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
163 [build-artefacts-issue]: https://github.com/snowleopard/hadrian/issues/113
164 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
165 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
166 [dynamic-issue]: https://github.com/snowleopard/hadrian/issues/4
167 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
168 [flavours-issue]: https://github.com/snowleopard/hadrian/issues/188
169 [cross-compilation-issue]: https://github.com/snowleopard/hadrian/issues/177
170 [install-issue]: https://github.com/snowleopard/hadrian/issues/219
171 [milestones]: https://github.com/snowleopard/hadrian/milestones
172 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors