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