Merge pull request #262 from alexbiehl/patch-1
[ghc.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 and initial
9 ideas behind the project you can find more details on the [wiki page][ghc-shake-wiki]
10 and in this [blog post][blog-post-1]. This project was formerly known as *Shaking-up-GHC*.
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 ([#1174](https://ghc.haskell.org/trac/ghc/ticket/11744)). To mitigate the problem place something like 
47   ````haskell
48   userArgs :: Args
49   userArgs = builder (Configure ".") ? arg "--with-nm=$(xcrun --find nm-classic)"
50   ````
51  in your `UserSettings.hs`.
52
53 Using the build system
54 ----------------------
55 Once your first build is successful, simply run `build` to rebuild. Most build artefacts
56 are placed into `_build` and `inplace` directories ([#113][build-artefacts-issue]).
57
58 #### Command line flags
59
60 In addition to standard Shake flags (try `--help`), the build system
61 currently supports several others:
62 * `--flavour=FLAVOUR`: choose a build flavour. Two settings are currently supported:
63 `default` and `quick` (adds `-O0` flag to all GHC invocations and disables library
64 profiling, which speeds up builds by 3-4x).
65
66 * `--haddock`: build Haddock documentation.
67
68 * `--progress-colour=MODE`: choose whether to use colours when printing build progress
69 info. There are three settings: `never` (do not use colours), `auto` (attempt to detect
70 whether the console supports colours; this is the default setting), and `always` (use
71 colours).
72
73 * `--progress-info=STYLE`: choose how build progress info is printed. There are four
74 settings: `none`, `brief` (one line per build command), `normal` (typically a box per
75 build command; this is the default setting), and `unicorn` (when `normal` just won't do).
76
77 * `--skip-configure`: use this flag to suppress the default behaviour of Hadrian that
78 runs the `boot` and `configure` scripts automatically if need be, so that you don't have
79 to remember to run them manually. With `--skip-configure` you will need to manually run:
80
81     ```bash
82     ./boot
83     ./configure # On Windows run ./configure --enable-tarballs-autodownload
84     ```
85 as you normally do when using `make`. Beware, by default Hadrian may do network I/O on
86 Windows to download necessary tarballs, which may sometimes be undesirable; `--skip-configure`
87 is your friend in such cases.
88
89 * `--split-objects`: generate split objects, which are switched off by default. Due to
90 a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.
91
92 * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages
93 by Shake oracles.
94
95 #### User settings
96
97 The `make`-based build system uses `mk/build.mk` to specify user build settings. We
98 use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user-settings.md).
99
100 #### Clean and full rebuild
101
102 * `build clean` removes all build artefacts. Note, we are working towards a
103 complete separation of GHC sources and build artefacts: [#113][build-artefacts-issue].
104
105 * `build -B` forces Shake to rerun all rules, even if results of the previous build
106 are still in the GHC tree. 
107
108 #### Testing
109
110 * `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
111 directory. This can be used instead of `sh validate --fast --no-clean` in the existing
112 build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
113
114 * `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
115 script with appropriate flags. The current implementation is limited and cannot
116 replace the `validate` script (see [#187][validation-issue]).
117
118 * `build selftest` runs tests of the build system. Current test coverage is close to
119 zero (see [#197][test-issue]).
120
121 Current limitations
122 -------------------
123 The new build system still lacks many important features:
124 * We only build `vanilla` and `profiling` way: [#4][dynamic-issue].
125 * Validation is not implemented: [#187][validation-issue].
126 * Only HTML Haddock documentation is supported (use `--haddock` flag). 
127 * Build flavours and conventional command line flags are not implemented: [#188][flavours-issue].
128 * Cross-compilation is not implemented: [#177][cross-compilation-issue].
129 * There is no support for installation or binary/source distribution: [#219][install-issue].
130
131 Check out [milestones] to see when we hope to resolve the above limitations.
132
133 How to contribute
134 -----------------
135
136 The best way to contribute is to try the new build system, report the issues
137 you found, and attempt to fix them. Please note the codebase is very unstable
138 at present and we expect a lot of further refactoring. The documentation is
139 currently non-existent, but we are working on it: [#55][comments-issue],
140 [#56][doc-issue]. See also [#239](https://github.com/snowleopard/hadrian/issues/239)
141 for a list of issues on the critical path.
142
143 Acknowledgements
144 ----------------
145
146 I started this project as part of my 6-month research visit to Microsoft
147 Research Cambridge, which was funded by Newcastle University, EPSRC, and
148 Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
149 and Simon Marlow for kick-starting the project and for their guidance. Last
150 but not least, big thanks to the project [contributors][contributors], who
151 helped me endure and enjoy the project.
152
153 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
154 [shake]: https://github.com/ndmitchell/shake/blob/master/README.md
155 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
156 [ghc-shake-wiki]: https://ghc.haskell.org/trac/ghc/wiki/Building/Shake
157 [blog-post-1]: https://blogs.ncl.ac.uk/andreymokhov/shaking-up-ghc
158 [issues]: https://github.com/snowleopard/hadrian/issues
159 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
160 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
161 [windows-build]: https://github.com/snowleopard/hadrian/blob/master/doc/windows.md
162 [build-artefacts-issue]: https://github.com/snowleopard/hadrian/issues/113
163 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
164 [test-issue]: https://github.com/snowleopard/hadrian/issues/197
165 [dynamic-issue]: https://github.com/snowleopard/hadrian/issues/4
166 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
167 [flavours-issue]: https://github.com/snowleopard/hadrian/issues/188
168 [cross-compilation-issue]: https://github.com/snowleopard/hadrian/issues/177
169 [install-issue]: https://github.com/snowleopard/hadrian/issues/219
170 [milestones]: https://github.com/snowleopard/hadrian/milestones
171 [comments-issue]: https://github.com/snowleopard/hadrian/issues/55
172 [doc-issue]: https://github.com/snowleopard/hadrian/issues/56
173 [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors