Major rewrite before the first release
authorAndrey Mokhov <andrey.mokhov@gmail.com>
Fri, 22 Jan 2016 02:07:49 +0000 (02:07 +0000)
committerAndrey Mokhov <andrey.mokhov@gmail.com>
Fri, 22 Jan 2016 02:07:49 +0000 (02:07 +0000)
README.md

index 8651b9b..e51e1e0 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,74 +3,112 @@ Shaking up GHC
 
 [![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)
 
-
-As part of my 6-month research secondment to Microsoft Research in Cambridge
-I am taking up the challenge of migrating the current [GHC][ghc] build system
-based on standard `make` into a new and (hopefully) better one based on
-[Shake][shake]. If you are curious about the project you can find more details
-on the [wiki page][ghc-shake-wiki] and in this [blog post][shake-blog-post].
-
-This is supposed to go into the `shake-build` directory of the GHC source tree.
+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].
 
 [Join us on #shaking-up-ghc on Freenode](irc://chat.freenode.net/#shaking-up-ghc).
 
-Trying it
----------
-
-Please see the [Preparation][ghc-preparation] on the GHC wiki
-for general preparation. The preparation steps for the `shake` build system are
-identical to those for the `make` build system. This means that you don't need
-to adjust anything if you are already familiar with building ghc using the `make`
-build system.
-
-Furthermore, we depend on the following packages which need to be installed:
-`ansi-terminal`, `mtl`, `shake`, `QuickCheck`.
-
-### Getting the source and configuring GHC
-
-```bash
-git clone --recursive git://git.haskell.org/ghc.git
-cd ghc
-git clone git://github.com/snowleopard/shaking-up-ghc shake-build
-./boot
-./configure                                # on linux / os x
-./configure --enable-tarballs-autodownload # on windows
-```
-
-### Configuring the build process
-
-`ghc` uses `mk/build.mk` to configure the build process. `shaking-up-ghc`
-uses `src/Settings/User.hs` for build specification.
-
-### Building GHC using `shaking-up-ghc`
-
-```bash
-./shake-build/build.sh       # linux / os x: to run the script directly.
-./shake-build/build.cabal.sh # linux / os x: OR to install the build system in a Cabal sandbox and then run it.
-shake-build/build.bat        # windows
-```
-
-Also see the [Building GHC on Windows guide][ghc-windows-building-guide].
+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`.
+
+* Get the sources. It is important for the build system to be in the `shake-build` directory of the GHC source tree:
+
+    ```bash
+    git clone --recursive git://git.haskell.org/ghc.git
+    cd ghc
+    git clone git://github.com/snowleopard/shaking-up-ghc shake-build
+    ```
+* Start your first build:
+
+    ```bash
+    shake-build/build.sh --configure
+    ```
+On Windows, use `build.bat` instead and pass an extra flag to configure (also see [building on Windows][ghc-windows-quick-build]):
+    ```bash
+    shake-build/build.bat --configure=--enable-tarballs-autodownload
+    ```
+If you are interested in building in a Cabal sandbox, have a look at `shake-build/build.cabal.sh`.
+
+Using the build system
+----------------------
+Once your first build is successful, simply run `shake-build/build.sh` or `shake-build/build.bat`
+to rebuild (you no longer need to use the `--configure` flag). Use `-j` flag to enable parallelism.
+
+### Command line flags
+
+In addition to standard Shake flags (try `--help`), the build system
+currently supports several others:
+* `--configure[=ARGS]`: run the `configure` script forwarding `ARGS` as command line
+arguments; also run the `boot` script to create the `configure` script if necessary.
+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`.
+* `--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).
+* `--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.
+
+### User settings
+
+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
+experiment.
 
 ### Resetting the build
 
-To reset the new build system run the build script with `-B` flag. This forces Shake to rerun all rules, even if results of the previous build are still in the GHC tree. This is a temporary solution; we are working on a proper reset functionality ([#131](https://github.com/snowleopard/shaking-up-ghc/issues/131)).
+To reset the new build system run the build script with `-B` flag. This forces Shake
+to rerun all rules, even if results of the previous build are still in the GHC tree.
+This is a temporary solution; we are working on proper reset functionality ([#131][reset-issue]).
 
+Current limitations
+-------------------
+The new build system still lacks many important features:
+* We only build `vanilla` way.
+* Documentation is broken: [#98][haddock-issue].
+* Validation is not implemented.
+* Build flavours and conventional command line flags are not implemented.
+* Cross-compilation is not implemented.
 
 How to contribute
 -----------------
 
 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
-at present and we expect a lot of further refactoring. Before attempting to
-fix any issue do make sure no one else is already working on it. The
-documentation is currently non-existent, but we will start addressing this
-once the codebase stabilises.
+at present and we expect a lot of further refactoring. The documentation is
+currently non-existent, but we are working on it.
 
+Acknowledgements
+----------------
+
+I started this project as part of my 6-month research visit to Microsoft
+Research in Cambridge. It was funded by Newcastle University, EPSRC, and
+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.
 
-[ghc-shake-wiki]: https://ghc.haskell.org/trac/ghc/wiki/Building/Shake
-[ghc-preparation]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
-[ghc-windows-building-guide]: https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows
 [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
-[shake-blog-post]: https://blogs.ncl.ac.uk/andreymokhov/shaking-up-ghc
 [shake]: https://github.com/ndmitchell/shake/blob/master/README.md
+[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
+[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
+[reset-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/131
+[haddock-issue]: https://github.com/snowleopard/shaking-up-ghc/issues/98
+[contributors]: https://github.com/snowleopard/shaking-up-ghc/graphs/contributors