[commit: ghc] wip/nfs-locking: Add a doc on build flavours (ff9e5b6)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/nfs-locking
Link       : http://ghc.haskell.org/trac/ghc/changeset/ff9e5b6362b5112a06f7018a5462639c9ef4d83c/ghc

>---------------------------------------------------------------

commit ff9e5b6362b5112a06f7018a5462639c9ef4d83c
Author: Andrey Mokhov <andrey.mokhov at gmail.com>
Date:   Thu Jan 12 01:00:53 2017 +0000

    Add a doc on build flavours
    
    See #239, #268.


>---------------------------------------------------------------

ff9e5b6362b5112a06f7018a5462639c9ef4d83c
 doc/flavours.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)

diff --git a/doc/flavours.md b/doc/flavours.md
new file mode 100644
index 0000000..dc672a9
--- /dev/null
+++ b/doc/flavours.md
@@ -0,0 +1,162 @@
+# Build flavours
+
+Hadrian supports a few predefined _build flavours_, i.e. collections of build
+settings that fully define a GHC build (see `src/Flavour.hs`). Users can add their
+own build flavours if need be, as described
+[here](https://github.com/snowleopard/hadrian/blob/master/doc/user-settings.md#build-flavour).
+
+## Arguments
+
+The following table summarises extra arguments passed to GHC in different build flavours.
+There are four groups of arguments: arguments in `hsDefault` are passed to GHC for all Haskell
+source files, `hsLibrary` arguments are added when compiling libraries, `hsCompiler`
+when compiling the `compiler` library, and `hsGhc` when compiling/linking the GHC program.
+
+<table>
+  <tr>
+    <th rowspan="3">Flavour</th>
+    <th colspan="8">Extra arguments</th>
+  </tr>
+  <tr>
+    <th colspan="2">hsDefault</td>
+    <th colspan="2">hsLibrary</td>
+    <th colspan="2">hsCompiler</td>
+    <th colspan="2">hsGhc</td>
+  </tr>
+  <tr>
+    <th>stage0</td>
+    <th>stage1+</td>
+    <th>stage0</td>
+    <th>stage1+</td>
+    <th>stage0</td>
+    <th>stage1+</td>
+    <th>stage0</td>
+    <th>stage1+</td>
+  </tr>
+  <tr>
+    <th>default<br></td>
+    <td>-O<br>-H32<br></td>
+    <td>-O2<br>-H32m</td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+  </tr>
+  <tr>
+    <th>quick</td>
+    <td>-O0<br>-H64</td>
+    <td>-O0<br>-H64</td>
+    <td></td>
+    <td>-O</td>
+    <td>-O</td>
+    <td></td>
+    <td>-O</td>
+    <td></td>
+  </tr>
+  <tr>
+    <th>quickest</td>
+    <td>-O0<br>-H64</td>
+    <td>-O0<br>-H64</td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+  </tr>
+  <tr>
+    <th>perf</td>
+    <td>-O<br>-H64</td>
+    <td>-O<br>-H64</td>
+    <td></td>
+    <td>-O2</td>
+    <td>-O</td>
+    <td>-O2</td>
+    <td>-O</td>
+    <td>-O2</td>
+  </tr>
+  <tr>
+    <th>prof</td>
+    <td>-O0<br>-H64</td>
+    <td>-O0<br>-H64</td>
+    <td></td>
+    <td>-O</td>
+    <td>-O</td>
+    <td>-O</td>
+    <td>-O</td>
+    <td>-O</td>
+  </tr>
+  <tr>
+    <th>devel1</td>
+    <td>-O<br>-H64</td>
+    <td>-O<br>-H64</td>
+    <td></td>
+    <td>-dcore-lint</td>
+    <td>-O0<br>-DDEBUG</td>
+    <td></td>
+    <td>-O0<br>-DDEBUG</td>
+    <td></td>
+  </tr>
+  <tr>
+    <th>devel2</td>
+    <td>-O<br>-H64</td>
+    <td>-O<br>-H64</td>
+    <td></td>
+    <td>-dcore-lint</td>
+    <td></td>
+    <td>-O0<br>-DDEBUG</td>
+    <td></td>
+    <td>-O0<br>-DDEBUG</td>
+  </tr>
+</table>
+
+## Ways
+
+Libraries and GHC can be built in different _ways_, e.g. with or without profiling
+information. The following table lists ways that are built in different flavours.
+
+<table>
+  <tr>
+    <th rowspan="2">Flavour</th>
+    <th colspan="2">Library ways</th>
+    <th colspan="2">RTS ways</th>
+    <th colspan="2">Profiled GHC</th>
+  </tr>
+  <tr>
+    <th>stage0</td>
+    <th>stage1+</td>
+    <th>stage0</td>
+    <th>stage1+</td>
+    <th>stage0</td>
+    <th>stage1+</td>
+  </tr>
+  <tr>
+    <th>default<br>perf<br>prof<br>devel1<br>devel2</td>
+    <td>vanilla</td>
+    <td>vanilla<br>profiling</td>
+    <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging</td>
+    <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging<br>threadedProfiling<br></td>
+    <td>Only in<br>prof<br>flavour</td>
+    <td>Only in<br>prof<br>flavour</td>
+  </tr>
+  <tr>
+    <th>quick</td>
+    <td>vanilla</td>
+    <td>vanilla</td>
+    <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging</td>
+    <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging</td>
+    <td>No</td>
+    <td>No</td>
+  </tr>
+  <tr>
+    <th>quickest</td>
+    <td>vanilla</td>
+    <td>vanilla</td>
+    <td>vanilla<br>threaded (when --haddock)</td>
+    <td>vanilla<br>threaded (when --haddock)</td>
+    <td>No</td>
+    <td>No</td>
+  </tr>
+</table>