README.md 7.85 KB
Newer Older
1
Shaking up GHC
Andrey Mokhov's avatar
Andrey Mokhov committed
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)
Andrey Mokhov's avatar
Andrey Mokhov committed
5

6
7
8
9
10
This is a new build system for the [Glasgow Haskell Compiler][ghc]. It is based
on [Shake][shake] and we hope that it will eventually replace the current
[`make`-based build system][make]. If you are curious about the rationale and initial
ideas behind the project you can find more details on the [wiki page][ghc-shake-wiki]
and in this [blog post][blog-post-1].
11

12
13
14
15
The new build system can work side-by-side with the existing build system. Note, there is
some interaction between them: they put (some) build results in the same directories,
e.g. `inplace/bin/ghc-stage1`. 

Andrey Mokhov's avatar
Andrey Mokhov committed
16
[Join us on #shaking-up-ghc on Freenode](irc://chat.freenode.net/#shaking-up-ghc).
17

18
19
20
21
22
23
24
25
26
27
28
29
Your first build
----------------

Beware, the build system is in the alpha development phase. Things are shaky and often
break; there are numerous [known issues][issues]. Not afraid? Then put on the helmet and
follow these steps:

* If you have never built GHC before, start with the [preparation guide][ghc-preparation].

* This build system is written in Haskell (obviously) and depends on the following Haskell
packages, which need to be installed: `ansi-terminal`, `mtl`, `shake`, `QuickCheck`.

30
31
* Get the sources and run standard configuration scripts. It is important for the build
system to be in the `shake-build` directory of the GHC source tree:
32
33
34
35
36

    ```bash
    git clone --recursive git://git.haskell.org/ghc.git
    cd ghc
    git clone git://github.com/snowleopard/shaking-up-ghc shake-build
37
38
    ./boot
    ./configure # On Windows run ./configure --enable-tarballs-autodownload
39
    ```
40
41
42
43
    
* Build GHC using `shake-build/build.sh` or `shake-build/build.bat` (on Windows) instead
of `make`. You might want to enable parallelism with `-j`. We will further refer to the
build script simply as `build`. If you are interested in building in a Cabal sandbox
44
45
or using Stack, have a look at `build.cabal.sh` and `build.stack.sh` scripts. Also
see [instructions for building GHC on Windows using Stack][windows-build].
46
47
48

Using the build system
----------------------
49
50
Once your first build is successful, simply run `build` to rebuild. Most build artefacts
are placed into `.build` and `inplace` directories ([#113][build-artefacts-issue]).
51

52
#### Command line flags
53
54
55

In addition to standard Shake flags (try `--help`), the build system
currently supports several others:
56
* `--flavour=FLAVOUR`: choose a build flavour. Two settings are currently supported:
57
58
`default` and `quick` (adds `-O0` flag to all GHC invocations and disables library
profiling, which speeds up builds by 3-4x).
Andrey Mokhov's avatar
Andrey Mokhov committed
59
* `--haddock`: build Haddock documentation.
60
61
62
* `--progress-info=STYLE`: choose how build progress info is printed. There are four
settings: `none`, `brief` (one line per build command), `normal` (typically a box per
build command; this is the default setting), and `unicorn` (when `normal` just won't do).
Andrey Mokhov's avatar
Andrey Mokhov committed
63
64
65
66
67
68
69
* `--setup[=CONFIGURE_ARGS]`: setup the build system by running the `configure` script 
with `CONFIGURE_ARGS` arguments; also run the `boot` script to create the `configure`
script if necessary. On Windows, download the required tarballs by executing
`mk/get-win32-tarballs.sh` with appropriate parameters. You do not have to
use this functionality of the new build system; feel free to run `boot` and `configure`
scripts manually, as you do when using `make`. Beware: `--setup` uses network I/O 
which may sometimes be undesirable.
70
71
72
* `--split-objects`: generate split objects, which are switched off by default. Due to
a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag.

73
#### User settings
74
75
76

The `make`-based build system uses `mk/build.mk` to specify user build settings. We
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
82
* `build clean` removes all build artefacts. Note, we are working towards a
complete separation of GHC sources and build artefacts: [#113][build-artefacts-issue].
83

84
85
* `build -B` forces Shake to rerun all rules, even if results of the previous build
are still in the GHC tree. 
Andrey Mokhov's avatar
Andrey Mokhov committed
86
87
88

#### Testing

89
90
91
* `build validate` runs GHC tests by simply executing `make fast` in `testsuite/tests`
directory. This can be used instead of `sh validate --fast --no-clean` in the existing
build system. Note: this will rebuild Stage2 GHC, `ghc-pkg` and `hpc` if they are out of date.
Andrey Mokhov's avatar
Andrey Mokhov committed
92

93
94
95
* `build test` runs GHC tests by calling the `testsuite/driver/runtests.py` python
script with appropriate flags. The current implementation is limited and cannot
replace the `validate` script (see [#187][validation-issue]).
Andrey Mokhov's avatar
Andrey Mokhov committed
96

97
98
* `build selftest` runs tests of the build system. Current test coverage is close to
zero (see [#197][test-issue]).
99

100
101
102
Current limitations
-------------------
The new build system still lacks many important features:
Andrey Mokhov's avatar
Andrey Mokhov committed
103
* We only build `vanilla` and `profiling` way: [#4][dynamic-issue].
104
* Validation is not implemented: [#187][validation-issue].
Andrey Mokhov's avatar
Andrey Mokhov committed
105
* Only HTML Haddock documentation is supported (use `--haddock` flag). 
106
107
* Build flavours and conventional command line flags are not implemented: [#188][flavours-issue].
* Cross-compilation is not implemented: [#177][cross-compilation-issue].
108

Andrey Mokhov's avatar
Andrey Mokhov committed
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
you found, and attempt to fix them. Please note the codebase is very unstable
116
at present and we expect a lot of further refactoring. The documentation is
117
118
currently non-existent, but we are working on it: [#55][comments-issue],
[#56][doc-issue].
119

120
121
122
123
Acknowledgements
----------------

I started this project as part of my 6-month research visit to Microsoft
Andrey Mokhov's avatar
Andrey Mokhov committed
124
Research Cambridge, which was funded by Newcastle University, EPSRC, and
125
126
127
128
Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell
and Simon Marlow for kick-starting the project and for their guidance. Last
but not least, big thanks to the project [contributors][contributors], who
helped me endure and enjoy the project.
129
130

[ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
131
[shake]: https://github.com/ndmitchell/shake/blob/master/README.md
132
133
134
135
136
137
[make]: https://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
[ghc-shake-wiki]: https://ghc.haskell.org/trac/ghc/wiki/Building/Shake
[blog-post-1]: https://blogs.ncl.ac.uk/andreymokhov/shaking-up-ghc
[issues]: https://github.com/snowleopard/shaking-up-ghc/issues
[ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
[ghc-windows-quick-build]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows#AQuickBuild
138
[windows-build]: https://github.com/snowleopard/shaking-up-ghc/blob/master/doc/windows.md
139
[build-artefacts-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/113
140
141
[ghc-split-objs-bug]: https://ghc.haskell.org/trac/ghc/ticket/11315
[user-settings]: https://github.com/snowleopard/shaking-up-ghc/blob/master/src/Settings/User.hs
Andrey Mokhov's avatar
Andrey Mokhov committed
142
[test-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/197
143
144
145
146
[dynamic-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/4
[validation-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/187
[flavours-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/188
[cross-compilation-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/177
Andrey Mokhov's avatar
Andrey Mokhov committed
147
[milestones]: https://github.com/snowleopard/shaking-up-ghc/milestones
148
149
[comments-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/55
[doc-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/56
150
[contributors]: https://github.com/snowleopard/shaking-up-ghc/graphs/contributors