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