Add a note on validate target
[hadrian.git] / README.md
1 Shaking up GHC
2 ==============
3
4 [![Linux & OS X status](https://img.shields.io/travis/snowleopard/shaking-up-ghc/master.svg?label=Linux%20%26%20OS%20X)](https://travis-ci.org/snowleopard/shaking-up-ghc) [![Windows status](https://img.shields.io/appveyor/ci/snowleopard/shaking-up-ghc/master.svg?label=Windows)](https://ci.appveyor.com/project/snowleopard/shaking-up-ghc)
5
6 This 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].
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 [Join us on #shaking-up-ghc on Freenode](irc://chat.freenode.net/#shaking-up-ghc).
17
18 Your first build
19 ----------------
20
21 Beware, the build system is in the alpha development phase. Things are shaky and often
22 break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
23 follow these steps:
24
25 * If you have never built GHC before, start with the [preparation guide][ghc-preparation].
26
27 * This build system is written in Haskell (obviously) and depends on the following Haskell
28 packages, which need to be installed: `ansi-terminal`, `mtl`, `shake`, `QuickCheck`.
29
30 * Get the sources. It is important for the build system to be in the `shake-build` directory of the GHC source tree:
31
32     ```bash
33     git clone --recursive git://git.haskell.org/ghc.git
34     cd ghc
35     git clone git://github.com/snowleopard/shaking-up-ghc shake-build
36     ```
37 * Start your first build (you might want to enable parallelism with `-j`):
38
39     ```bash
40     shake-build/build.sh --configure
41     ```
42 On Windows, use `build.bat` instead and pass an extra flag to configure (also see [building on Windows][ghc-windows-quick-build]):
43     ```bash
44     shake-build/build.bat --configure=--enable-tarballs-autodownload
45     ```
46 If you are interested in building in a Cabal sandbox or using Stack, have a look at `shake-build/build.cabal.sh` and `shake-build/build.stack.sh` scripts.
47
48 Using the build system
49 ----------------------
50 Once your first build is successful, simply run `shake-build/build.sh` or `shake-build/build.bat`
51 to rebuild (you no longer need to use the `--configure` flag). Most build artefacts are placed
52 into `.build` and `inplace` directories ([#113][build-artefacts-issue]).
53
54 #### Command line flags
55
56 In addition to standard Shake flags (try `--help`), the build system
57 currently supports several others:
58 * `--configure[=ARGS]`: run the `configure` script forwarding `ARGS` as command line
59 arguments; also run the `boot` script to create the `configure` script if necessary.
60 You do not have to use this functionality of the new build system; feel free to run
61 `boot` and `configure` scripts manually, as you do when using `make`.
62 * `--flavour=FLAVOUR`: choose a build flavour. Two settings are currently supported:
63 `default` and `quick` (adds `-O0` flag to all GHC invocations speeding up builds by 3x).
64 * `--progress-info=STYLE`: choose how build progress info is printed. There are four
65 settings: `none`, `brief` (one line per build command), `normal` (typically a box per
66 build command; this is the default setting), and `unicorn` (when `normal` just won't do).
67 * `--split-objects`: generate split objects, which are switched off by default. Due to
68 a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.
69
70 #### User settings
71
72 The `make`-based build system uses `mk/build.mk` to specify user build settings. We
73 use [`src/Settings/User.hs`][user-settings] for the same purpose. Feel free to
74 experiment following the Haddock comments.
75
76 #### Clean and full rebuild
77
78 * `shake-build/build.sh clean` removes all build artefacts. Note, we are working
79 towards a complete separation of GHC sources and build artefacts: [#113][build-artefacts-issue].
80
81 * `shake-build/build.sh -B` forces Shake to rerun all rules, even if results of
82 the previous build are still in the GHC tree. 
83
84 #### Testing
85
86 * `shake-build/build.sh validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
87 directory. This can be used instead of `sh validate --fast --no-clean` in the existing build system.
88 Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
89
90 * `shake-build/build.sh test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
91 script with appropriate flags. The current implementation is limited and cannot replace the
92 `validate` script (see [#187][validation-issue]).
93
94 * `shake-build/build.sh selftest` runs tests of the build system. Current test
95 coverage is close to zero (see [#197][test-issue]).
96
97 Current limitations
98 -------------------
99 The new build system still lacks many important features:
100 * We only build `vanilla` way: [#4][dynamic-issue], [#186][profiling-issue].
101 * Documentation is broken: [#98][haddock-issue].
102 * Validation is not implemented: [#187][validation-issue].
103 * Build flavours and conventional command line flags are not implemented: [#188][flavours-issue].
104 * Cross-compilation is not implemented: [#177][cross-compilation-issue].
105
106 Check out [milestones] to see when we hope to resolve the above limitations.
107
108 How to contribute
109 -----------------
110
111 The best way to contribute is to try the new build system, report the issues
112 you found, and attempt to fix them. Please note the codebase is very unstable
113 at present and we expect a lot of further refactoring. The documentation is
114 currently non-existent, but we are working on it: [#55][comments-issue],
115 [#56][doc-issue].
116
117 Acknowledgements
118 ----------------
119
120 I started this project as part of my 6-month research visit to Microsoft
121 Research Cambridge, which was funded by Newcastle University, EPSRC, and
122 Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
123 and Simon Marlow for kick-starting the project and for their guidance. Last
124 but not least, big thanks to the project [contributors][contributors], who
125 helped me endure and enjoy the project.
126
127 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
128 [shake]: https://github.com/ndmitchell/shake/blob/master/README.md
129 [make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
130 [ghc-shake-wiki]: https://ghc.haskell.org/trac/ghc/wiki/Building/Shake
131 [blog-post-1]: https://blogs.ncl.ac.uk/andreymokhov/shaking-up-ghc
132 [issues]: https://github.com/snowleopard/shaking-up-ghc/issues
133 [ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
134 [ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
135 [build-artefacts-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/113
136 [ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
137 [user-settings]: https://github.com/snowleopard/shaking-up-ghc/blob/master/src/Settings/User.hs
138 [test-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/197
139 [dynamic-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/4
140 [profiling-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/186
141 [haddock-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/98
142 [validation-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/187
143 [flavours-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/188
144 [cross-compilation-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/177
145 [milestones]: https://github.com/snowleopard/shaking-up-ghc/milestones
146 [comments-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/55
147 [doc-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/56
148 [contributors]: https://github.com/snowleopard/shaking-up-ghc/graphs/contributors