Hadrian: add LLVM flavours
[ghc.git] / hadrian / doc / flavours.md
1 # Build flavours
2
3 Hadrian supports a few predefined _build flavours_, i.e. collections of build
4 settings that fully define a GHC build (see `src/Flavour.hs`). Users can add their
5 own build flavours if need be, as described
6 [here](https://github.com/snowleopard/hadrian/blob/master/doc/user-settings.md#build-flavour).
7
8 ## Arguments
9
10 The following table summarises extra arguments passed to GHC in different build flavours.
11 There are four groups of arguments: arguments in `hsDefault` are passed to GHC for all Haskell
12 source files, `hsLibrary` arguments are added when compiling libraries, `hsCompiler`
13 when compiling the `compiler` library, and `hsGhc` when compiling/linking the GHC program.
14
15 <table>
16   <tr>
17     <th rowspan="3">Flavour</th>
18     <th colspan="8">Extra arguments</th>
19   </tr>
20   <tr>
21     <th colspan="2">hsDefault</td>
22     <th colspan="2">hsLibrary</td>
23     <th colspan="2">hsCompiler</td>
24     <th colspan="2">hsGhc</td>
25   </tr>
26   <tr>
27     <th>stage0</td>
28     <th>stage1+</td>
29     <th>stage0</td>
30     <th>stage1+</td>
31     <th>stage0</td>
32     <th>stage1+</td>
33     <th>stage0</td>
34     <th>stage1+</td>
35   </tr>
36   <tr>
37     <th>default<br></td>
38     <td>-O<br>-H64m<br></td>
39     <td>-O2<br>-H64m</td>
40     <td></td>
41     <td></td>
42     <td></td>
43     <td></td>
44     <td></td>
45     <td></td>
46   </tr>
47   <tr>
48     <th>quick</td>
49     <td>-O0<br>-H64m</td>
50     <td>-O0<br>-H64m</td>
51     <td></td>
52     <td>-O</td>
53     <td>-O2</td>
54     <td>-O</td>
55     <td>-O</td>
56     <td></td>
57   </tr>
58   <tr>
59     <th>quickest</td>
60     <td>-O0<br>-H64m</td>
61     <td>-O0<br>-H64m</td>
62     <td></td>
63     <td></td>
64     <td>-O</td>
65     <td></td>
66     <td>-O</td>
67     <td></td>
68   </tr>
69   <tr>
70     <th>perf</td>
71     <td>-O<br>-H64m</td>
72     <td>-O<br>-H64m</td>
73     <td></td>
74     <td>-O2</td>
75     <td>-O2</td>
76     <td>-O2</td>
77     <td>-O</td>
78     <td>-O2</td>
79   </tr>
80   <tr>
81     <th>prof</td>
82     <td>-O0<br>-H64m</td>
83     <td>-O0<br>-H64m</td>
84     <td></td>
85     <td>-O</td>
86     <td>-O2</td>
87     <td>-O</td>
88     <td>-O</td>
89   </tr>
90   <tr>
91     <th>devel1</td>
92     <td>-O<br>-H64m</td>
93     <td>-O<br>-H64m</td>
94     <td></td>
95     <td>-dcore-lint</td>
96     <td>-O0<br>-DDEBUG</td>
97     <td></td>
98     <td>-O0<br>-DDEBUG</td>
99     <td></td>
100   </tr>
101   <tr>
102     <th>devel2</td>
103     <td>-O<br>-H64m</td>
104     <td>-O<br>-H64m</td>
105     <td></td>
106     <td>-dcore-lint</td>
107     <td>-O2</td>
108     <td>-O0<br>-DDEBUG</td>
109     <td></td>
110     <td>-O0<br>-DDEBUG</td>
111   </tr>
112   <tr>
113     <th>quick-llvm</td>
114     <td>-O0<br>-H64m<br>-fllvm</td>
115     <td>-O0<br>-H64m<br>-fllvm</td>
116     <td></td>
117     <td>-O</td>
118     <td>-O</td>
119     <td></td>
120     <td>-O</td>
121     <td></td>
122   </tr>
123   <tr>
124     <th>perf-llvm</td>
125     <td>-O<br>-H64m<br>-fllvm</td>
126     <td>-O<br>-H64m<br>-fllvm</td>
127     <td></td>
128     <td>-O2</td>
129     <td>-O</td>
130     <td>-O2</td>
131     <td>-O</td>
132     <td>-O2</td>
133   </tr>
134   <tr>
135     <th>prof-llvm</td>
136     <td>-O0<br>-H64m<br>-fllvm</td>
137     <td>-O0<br>-H64m<br>-fllvm</td>
138     <td></td>
139     <td>-O</td>
140     <td>-O</td>
141     <td>-O</td>
142     <td>-O</td>
143     <td>-O</td>
144   </tr>
145 </table>
146
147 ## Ways
148
149 Libraries and GHC can be built in different _ways_, e.g. with or without profiling
150 information. The following table lists ways that are built in different flavours.
151
152 <table>
153     <tr>
154         <th rowspan="2">Flavour</th>
155         <th colspan="2">Library ways</th>
156         <th colspan="2">RTS ways</th>
157         <th colspan="2">Profiled GHC</th>
158     </tr>
159     <tr>
160         <th>stage0</th>
161         <th>stage1+</th>
162         <th>stage0</th>
163         <th>stage1+</th>
164         <th>stage0</th>
165         <th>stage1+</th>
166     </tr>
167     <tr>
168     <th>default<br>perf<br>prof<br>devel1<br>devel2<br>perf-llvm<br>prof-llvm</td>
169     <td>vanilla</td>
170     <td>vanilla<br>profiling<br>dynamic</td>
171     <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging
172         <br>debugDynamic<br>threadedDynamic<br>threadedDebugDynamic
173         <br>loggingDynamic<br>threadedLoggingDynamic
174     </td>
175     <td>
176         logging<br>debug<br>threaded<br>threadedDebug<br>
177         threadedLogging<br>threadedProfiling
178         <br>debugDynamic<br>threadedDynamic<br>threadedDebugDynamic
179         <br>loggingDynamic<br>threadedLoggingDynamic
180     </td>
181     <td>Only in<br>prof<br>flavour</td>
182     <td>Only in<br>prof<br>flavour</td>
183 </tr>
184 <tr>
185     <th>quick<br>quick-llvm</th>
186     <td>vanilla</td>
187     <td>vanilla<br>dynamic</td>
188     <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging
189         <br>debugDynamic<br>threadedDynamic<br>threadedDebugDynamic
190         <br>loggingDynamic<br>threadedLoggingDynamic
191     </td>
192     <td>logging<br>debug<br>threaded<br>threadedDebug<br>threadedLogging
193         <br>debugDynamic<br>threadedDynamic<br>threadedDebugDynamic
194         <br>loggingDynamic<br>threadedLoggingDynamic
195     </td>
196     <td>No</td>
197     <td>No</td>
198 </tr>
199 <tr>
200     <th>quickest</th>
201     <td>vanilla</td>
202     <td>vanilla</td>
203     <td>vanilla<br>threaded</td>
204     <td>vanilla<br>threaded</td>
205     <td>No</td>
206     <td>No</td>
207 </tr>
208 </table>