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