Commit ec752c4c authored by Andrey Mokhov's avatar Andrey Mokhov Committed by Ben Gamari

Hadrian: Update README.md

* Update or remove a few outdated paragraphs
* Use consistent naming (e.g. "Stage1" instead of occasionally "stage1")
* Rewrite acknowledgements
* Some more minor revisions
parent 0f3c04e4
Hadrian Hadrian
======= =======
[![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) [![OS X status](https://img.shields.io/circleci/project/github/snowleopard/hadrian.svg?label=OS%20X)](https://circleci.com/gh/snowleopard/hadrian) Hadrian is a new build system for the [Glasgow Haskell Compiler][ghc]. It is
based on the [Shake][shake] library and we hope that it will replace the current
Hadrian is a new build system for the [Glasgow Haskell Compiler][ghc]. It is based [Make-based build system][make] starting from GHC 8.8. If you are curious about
on [Shake][shake] and we hope that it will soon replace the current the rationale behind the
[Make-based build system][make]. If you are curious about the rationale behind the
project and the architecture of the build system you can find more details in project and the architecture of the build system you can find more details in
this [Haskell Symposium 2016 paper](https://dl.acm.org/authorize?N41275) and this this [Haskell Symposium 2016 paper](https://dl.acm.org/authorize?N41275) and this
[Haskell eXchange 2016 talk][talk]. [Haskell eXchange 2016 talk][talk].
...@@ -18,7 +17,7 @@ if you'd like to start using Hadrian for building GHC. ...@@ -18,7 +17,7 @@ if you'd like to start using Hadrian for building GHC.
Your first build Your first build
---------------- ----------------
Hadrian has not entirely caught up with the make build system. Not afraid? Hadrian has not entirely caught up with the Make build system. Not afraid?
Then put on the helmet and run the following commands from the root of the GHC Then put on the helmet and run the following commands from the root of the GHC
tree: tree:
...@@ -46,7 +45,6 @@ another one, e.g. based on Cabal sandboxes (`build.cabal.*`) or ...@@ -46,7 +45,6 @@ another one, e.g. based on Cabal sandboxes (`build.cabal.*`) or
Stack (`build.stack.*`). Also see Stack (`build.stack.*`). Also see
[instructions for building GHC on Windows using Stack][windows-build]. [instructions for building GHC on Windows using Stack][windows-build].
* Hadrian is written in Haskell and depends on `shake` (plus a few packages that * Hadrian is written in Haskell and depends on `shake` (plus a few packages that
`shake` depends on), `mtl`, `quickcheck`, and GHC core libraries. `shake` depends on), `mtl`, `quickcheck`, and GHC core libraries.
...@@ -66,7 +64,7 @@ currently supports several others: ...@@ -66,7 +64,7 @@ currently supports several others:
* `--build-root=PATH` or `-oPATH`: specify the directory in which you want to * `--build-root=PATH` or `-oPATH`: specify the directory in which you want to
store all build products. By default Hadrian builds everything in the `_build/` store all build products. By default Hadrian builds everything in the `_build/`
subdirectory of the GHC source tree. Unlike the Make build system, Hadrian subdirectory of the GHC source tree. Unlike the Make build system, Hadrian
doesn't have any "inplace" logic left anymore. This option is therefore useful doesn't have any "inplace" logic left any more. This option is therefore useful
for GHC developers who want to build GHC in different ways or at different for GHC developers who want to build GHC in different ways or at different
commits, from the same source directory, and have the build products sit in commits, from the same source directory, and have the build products sit in
different, isolated folders. different, isolated folders.
...@@ -78,95 +76,100 @@ normally do when using Make (typically only in the first build): ...@@ -78,95 +76,100 @@ normally do when using Make (typically only in the first build):
./boot ./boot
./configure # On Windows run ./configure --enable-tarballs-autodownload ./configure # On Windows run ./configure --enable-tarballs-autodownload
``` ```
Beware that with this flag Hadrian may do network I/O on Windows to download necessary Beware that with this flag Hadrian may do network I/O on Windows to download
tarballs, which may sometimes be undesirable. necessary tarballs, which may sometimes be undesirable.
* `--flavour=FLAVOUR`: choose a build flavour. The following settings are currently supported: * `--flavour=FLAVOUR`: choose a build flavour. The following settings are
`default`, `quick`, `quickest`, `perf`, `prof`, `devel1` and `devel2`. As an example, the currently supported: `default`, `quick`, `quickest`, `perf`, `prof`, `devel1`
`quickest` flavour adds `-O0` flag to all GHC invocations and builds libraries only in the and `devel2`. As an example, the `quickest` flavour adds `-O0` flag to all GHC
`vanilla` way, which speeds up builds by 3-4x. Build flavours are documented invocations and builds libraries only in the `vanilla` way, which speeds up
builds by 3-4x. Build flavours are documented
[here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md). [here](https://github.com/snowleopard/hadrian/blob/master/doc/flavours.md).
* `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its source files * `--freeze1`: freeze Stage1 GHC, i.e. do not rebuild it even if some of its
are out-of-date. This allows to significantly reduce the rebuild time when you are working source files are out-of-date. This allows to significantly reduce the rebuild
on a feature that affects both Stage1 and Stage2 compilers, but may lead to incorrect time when you are working on a feature that affects both Stage1 and Stage2
build results. To unfreeze Stage1 GHC simply drop the `--freeze1` flag and Hadrian will compilers, but may lead to incorrect build results. To unfreeze Stage1 GHC
rebuild all out-of-date files. simply drop the `--freeze1` flag and Hadrian will rebuild all out-of-date files.
* `--integer-simple`: build GHC using the `integer-simple` integer library (instead * `--integer-simple`: build GHC using the `integer-simple` integer library
of `integer-gmp`). (instead of `integer-gmp`).
* `--progress-colour=MODE`: choose whether to use colours when printing build progress * `--progress-colour=MODE`: choose whether to use colours when printing build
info. There are three settings: `never` (do not use colours), `auto` (attempt to detect progress info. There are three settings: `never` (do not use colours), `auto`
whether the console supports colours; this is the default setting), and `always` (use (attempt to detect whether the console supports colours; this is the default
colours). setting), and `always` (use colours).
* `--progress-info=STYLE`: choose how build progress info is printed. There are four * `--progress-info=STYLE`: choose how build progress info is printed. There are
settings: `none`, `brief` (one line per build command; this is the default setting), four settings: `none`, `brief` (one line per build command; this is the default
`normal` (typically a box per build command), and `unicorn` (when `normal` just won't do). setting), `normal` (typically a box per build command), and `unicorn` (when
`normal` just won't do).
* `--split-objects`: generate split objects, which are switched off by default. Due to * `--split-objects`: generate split objects, which are switched off by default.
a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using this flag. Due to a GHC [bug][ghc-split-objs-bug], you need a full clean rebuild when using
this flag.
* `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic messages * `--verbose`: run Hadrian in verbose mode. In particular this prints diagnostic
by Shake oracles. messages by Shake oracles.
#### User settings #### User settings
The Make-based build system uses `mk/build.mk` to specify user build settings. We The Make-based build system uses `mk/build.mk` to specify user build settings.
use `hadrian/UserSettings.hs` for the same purpose, see [documentation](doc/user-settings.md). Hadrian uses `hadrian/UserSettings.hs` for the same purpose, see
[documentation](doc/user-settings.md).
#### Building libraries and executables #### Building libraries and executables
You can build a specific library or executable for a given stage by doing You can build a specific library or executable for a given stage by running
`build stage<N>:<lib|exe>:<package name>`. Examples: `build stage<N>:<lib|exe>:<package name>`. Examples:
``` sh ```sh
# build the stage 1 GHC compiler (the executable), the binary will be placed # Build the Stage1 GHC compiler, and place the binary to the directory
# under _build/stage0/bin/ghc (because it is built by the stage0 compiler). # _build/stage0/bin/ghc (because it is built by the Stage0 compiler).
build stage1:exe:ghc-bin build stage1:exe:ghc-bin
# build the stage 2 GHC compiler, the binary will be placed under # Build the Stage2 GHC compiler, and place the binary to the directory
# _build/stage1/bin/ghc (because it is built by the stage1 compiler). # _build/stage1/bin/ghc (because it is built by the Stage1 compiler).
build stage2:exe:ghc-bin build stage2:exe:ghc-bin
# build the ghc library with the boot compiler, and register it # Build the `ghc` library with the bootstrapping (Stage0) compiler, and register
# in the package database under _build/stage0/lib. # it in the package database stored in the directory _build/stage0/lib.
build stage0:lib:ghc build stage0:lib:ghc
# build the Cabal library with the stage 1 compiler and register it # Build the Cabal library with the Stage1 compiler and register it
# in the package database under _build/stage1/lib. # in the package database stored in the directory _build/stage1/lib.
# build the text library with the stage 2 compiler and register it # Build the `text` library with the Stage2 compiler and register it
# in the package database under _build/stage2/lib. # in the package database stored in the directory _build/stage2/lib.
build stage2:lib:text build stage2:lib:text
# build the stage 2 haddock executable and place the program under # Build Haddock using the Stage1 compiler and place the binary into the
# _build/stage1/haddock. # directory _build/stage1/haddock.
build stage2:exe:haddock build stage1:exe:haddock
``` ```
#### Testing #### Testing
To run GHC's testsuite, use `build test`. See To run GHC testsuite, use `build test`. See
[doc/testsuite.md](doc/testsuite.md) to learn about all the options [doc/testsuite.md](doc/testsuite.md) to learn about all associated command line
you can use to mimic what the Make build system offers. flags, as well as about the equivalents of the features that the Make build
system offers.
`build selftest` runs tests of the build system. Current test coverage `build selftest` runs tests of the build system. The current test coverage
is close to zero (see [#197][test-issue]). is close to zero (see [#197][test-issue]).
#### Clean and full rebuild #### Clean and full rebuild
* `build clean` removes all build artefacts. * `build clean` removes all build artefacts.
* `build -B` forces Shake to rerun all rules, even if the previous build results are * `build -B` forces Shake to rerun all rules, even if the previous build results
are still up-to-date. are still up-to-date.
#### Documentation #### Documentation
To build GHC documentation, run `build docs`. Note that finer-grain documentation To build GHC documentation, run `build docs`. Note that finer-grain
targets (e.g. building only HTML documentation or only the GHC User's Guide) documentation targets (e.g. building only HTML documentation or only the GHC
are currently not supported. User's Guide) are currently not supported.
#### Source distribution #### Source distribution
...@@ -183,28 +186,28 @@ $ ./configure [--prefix=PATH] && make install ...@@ -183,28 +186,28 @@ $ ./configure [--prefix=PATH] && make install
workflow, for now. workflow, for now.
#### Building stage3 #### Building Stage3
It is possible to define a flavour which builds a `stage3` compiler, which is a It is possible to define a build flavour that builds a Stage3 compiler, which is
compiler built using `stage2`. This is useful for cross-compilation. Detailed a compiler built using Stage2. This is useful for cross-compilation. Detailed
instructions can be found in the instructions can be found in the corresponding
[user settings part of the manual](doc/user-settings.md#specifying-the-final-stage-to-build). [part of the user settings manual](doc/user-settings.md#specifying-the-final-stage-to-build).
Troubleshooting Troubleshooting
--------------- ---------------
Here are a few simple suggestions that might help you fix the build: Here are a few simple suggestions that might help you fix the build:
* Hadrian is occasionally broken by changes in GHC. If this happens, you might want to switch * If Hadrian fails with the message
to an earlier GHC commit. `Configuration file hadrian/cfg/system.config is missing`, you have probably
forgotten to pass the `--configure` flag during the first build.
* If Hadrian fails with the message `Configuration file hadrian/cfg/system.config is missing`, * If you need help in debugging Hadrian, read the
you have probably forgotten to pass the `--configure` flag during the first build. [wiki](https://github.com/snowleopard/hadrian/wiki)
* If you need help in debugging Hadrian, read the [wiki](https://github.com/snowleopard/hadrian/wiki)
and Shake's [debugging tutorial](https://shakebuild.com/debugging). and Shake's [debugging tutorial](https://shakebuild.com/debugging).
If everything fails, don't hesitate to [raise an issue](https://github.com/snowleopard/hadrian/issues/new). If nothing helps, don't hesitate to create a GHC Trac ticket, choosing the
component `Build System (Hadrian)`.
Current limitations Current limitations
------------------- -------------------
...@@ -212,32 +215,31 @@ The new build system still lacks many important features: ...@@ -212,32 +215,31 @@ The new build system still lacks many important features:
* Validation is not implemented: [#187][validation-issue]. * Validation is not implemented: [#187][validation-issue].
* Dynamic linking on Windows is not supported [#343][dynamic-windows-issue]. * Dynamic linking on Windows is not supported [#343][dynamic-windows-issue].
Check out [milestones] to see when we hope to resolve the above limitations.
How to contribute How to contribute
----------------- -----------------
The best way to contribute is to try the new build system, report the issues The best way to contribute is to try Hadrian, report the issues you found, and
you found, and attempt to fix them. Please note: the codebase is very unstable attempt to fix them. Documentation patches are particularly welcome. Please
at present and we expect a lot of further refactoring. If you would like to note: the codebase is still unstable and we expect some further refactoring. In
work on a particular issue, please let everyone know by adding a comment about particular, we would like to separate the general-purpose "Hadrian library" for
this. The issues that are currently on the critical path and therefore require building Haskell projects using Shake (`src/Hadrian/*`) from GHC specifics; see
particular attention are listed in [#239](https://github.com/snowleopard/hadrian/issues/239). [this issue](https://github.com/snowleopard/hadrian/issues/347).
Also have a look at [projects](https://github.com/snowleopard/hadrian/projects)
where open issues and pull requests are grouped into categories.
Acknowledgements Acknowledgements
---------------- ----------------
I started this project as part of my 6-month research visit to Microsoft The list of people who helped create Hadrian is long, and we hope that it will
Research Cambridge, which was funded by Newcastle University, EPSRC, and soon become even longer! The project was first developed in a separate GitHub
Microsoft Research. I would like to thank Simon Peyton Jones, Neil Mitchell repository, where you can find the list of original
and Simon Marlow for kick-starting the project and for their guidance. [contributors][contributors]. They had to stare at Makefiles for months, so give
Zhen Zhang has done fantastic work on Hadrian as part of his Summer of them all a round of applause. Simon Peyton Jones and Simon Marlow helped with
Haskell 2017 [project](https://summer.haskell.org/ideas.html#hadrian-ghc), deciphering these Makefiles, and Neil Mitchell patiently explained how to
solving a few heavy and long-overdue issues. Last but not least, big thanks translate Makefiles to (much nicer) Shakefiles.
to all other project [contributors][contributors], who helped me endure and
enjoy the project. The initial development of Hadrian was funded by Newcastle University, EPSRC and
Microsoft Research. Other organisations that contributed at various stages of
the project are Haskell.Org and Google (both through supporting summer student
projects), as well as Well-Typed.
[ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler [ghc]: https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler
[shake]: https://github.com/ndmitchell/shake [shake]: https://github.com/ndmitchell/shake
...@@ -252,5 +254,4 @@ enjoy the project. ...@@ -252,5 +254,4 @@ enjoy the project.
[validation-issue]: https://github.com/snowleopard/hadrian/issues/187 [validation-issue]: https://github.com/snowleopard/hadrian/issues/187
[dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343 [dynamic-windows-issue]: https://github.com/snowleopard/hadrian/issues/343
[bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219 [bin-dist-issue]: https://github.com/snowleopard/hadrian/issues/219
[milestones]: https://github.com/snowleopard/hadrian/milestones
[contributors]: https://github.com/snowleopard/hadrian/graphs/contributors [contributors]: https://github.com/snowleopard/hadrian/graphs/contributors
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment