users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[ghc.git] / docs / users_guide / flags.rst
1 .. _flag-reference:
2
3 Flag reference
4 ==============
5
6 This section is a quick-reference for GHC's command-line flags. For each
7 flag, we also list its static/dynamic status (see
8 :ref:`static-dynamic-flags`), and the flag's opposite (if available).
9
10 Verbosity options
11 -----------------
12
13 More details in :ref:`options-help`
14
15 .. tabularcolumns::
16     | p{\dimexpr 0.33\textwidth-2\tabcolsep} |
17       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
18       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
19       p{\dimexpr 0.26\textwidth-2\tabcolsep} |
20
21 .. flag-print::
22     :type: table
23     :category: verbosity
24
25 Alternative modes of operation
26 ------------------------------
27
28 More details in :ref:`modes`
29
30 .. tabularcolumns::
31     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
32       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
33       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
34       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
35
36 .. flag-print::
37     :type: table
38     :category: modes
39
40 Which phases to run
41 -------------------
42
43 More details in :ref:`options-order`
44
45 .. tabularcolumns::
46     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
47       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
48       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
49       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
50
51 .. flag-print::
52     :type: table
53     :category: phases
54
55 Redirecting output
56 ------------------
57
58 More details in :ref:`options-output`
59
60 .. tabularcolumns::
61     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
62       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
63       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
64       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
65
66 .. flag-print::
67     :type: table
68     :category: redirect-output
69
70 Keeping intermediate files
71 --------------------------
72
73 More details in :ref:`keeping-intermediates`
74
75 .. tabularcolumns::
76     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
77       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
78       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
79       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
80
81 .. flag-print::
82     :type: table
83     :category: keep-intermediates
84
85 Temporary files
86 ---------------
87
88 More details in :ref:`temp-files`
89
90 .. tabularcolumns::
91     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
92       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
93       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
94       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
95
96 .. flag-print::
97     :type: table
98     :category: temp-files
99
100 Finding imports
101 ---------------
102
103 More details in :ref:`search-path`
104
105 .. tabularcolumns::
106     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
107       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
108       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
109       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
110
111 .. flag-print::
112     :type: table
113     :category: search-path
114
115 Interface file options
116 ----------------------
117
118 More details in :ref:`hi-options`
119
120 .. tabularcolumns::
121     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
122       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
123       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
124       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
125
126 .. flag-print::
127     :type: table
128     :category: interface-files
129
130 Recompilation checking
131 ----------------------
132
133 More details in :ref:`recomp`
134
135 .. tabularcolumns::
136     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
137       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
138       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
139       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
140
141 .. flag-print::
142     :type: table
143     :category: recompilation
144
145 .. _interactive-mode-options:
146
147 Interactive-mode options
148 ------------------------
149
150 More details in :ref:`ghci-dot-files`
151
152 .. tabularcolumns::
153     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
154       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
155       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
156       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
157
158 .. flag-print::
159     :type: table
160     :category: interactive
161
162 Packages
163 --------
164
165 More details in :ref:`packages`
166
167 .. tabularcolumns::
168     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
169       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
170       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
171       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
172
173 .. flag-print::
174     :type: table
175     :category: packages
176
177 Language options
178 ----------------
179
180 Language options can be enabled either by a command-line option
181 ``-Xblah``, or by a ``{-# LANGUAGE blah #-}`` pragma in the file itself.
182 See :ref:`options-language`. Some options are enabled using ``-f*``
183 flags.
184
185 .. tabularcolumns::
186     | p{\dimexpr 0.36\textwidth-2\tabcolsep} |
187       p{\dimexpr 0.25\textwidth-2\tabcolsep} |
188       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
189       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
190
191 .. flag-print::
192     :type: table
193     :category: language
194
195 Warnings
196 --------
197
198 More details in :ref:`options-sanity`
199
200 .. tabularcolumns::
201     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
202       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
203       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
204       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
205
206 .. flag-print::
207     :type: table
208     :category: warnings
209
210 Optimisation levels
211 -------------------
212
213 These options are described in more detail in :ref:`options-optimise`.
214
215 See :ref:`options-f-compact` for a list of optimisations enabled on
216 level 1 and level 2.
217
218 .. tabularcolumns::
219     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
220       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
221       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
222       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
223
224 .. flag-print::
225     :type: table
226     :category: optimization-levels
227
228 .. _options-f-compact:
229
230 Individual optimisations
231 ------------------------
232
233 These options are described in more detail in :ref:`options-f`. If a
234 flag is implied by ``-O`` then it is also implied by ``-O2`` (unless
235 flag description explicitly says otherwise). If a flag is implied by
236 ``-O0`` only then the flag is not implied by ``-O`` and ``-O2``.
237
238 .. tabularcolumns::
239     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
240       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
241       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
242       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
243
244 .. flag-print::
245     :type: table
246     :category: optimization
247
248 Profiling options
249 -----------------
250
251 More details in :ref:`profiling`
252
253 .. tabularcolumns::
254     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
255       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
256       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
257       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
258
259 .. flag-print::
260     :type: table
261     :category: profiling
262
263 Program coverage options
264 ------------------------
265
266 More details in :ref:`hpc`
267
268 .. tabularcolumns::
269     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
270       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
271       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
272       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
273
274 .. flag-print::
275     :type: table
276     :category: coverage
277
278 C pre-processor options
279 -----------------------
280
281 More details in :ref:`c-pre-processor`
282
283 .. tabularcolumns::
284     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
285       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
286       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
287       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
288
289 .. flag-print::
290     :type: table
291     :category: cpp
292
293 Code generation options
294 -----------------------
295
296 More details in :ref:`options-codegen`
297
298 .. tabularcolumns::
299     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
300       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
301       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
302       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
303
304 .. flag-print::
305     :type: table
306     :category: codegen
307
308 Linking options
309 ---------------
310
311 More details in :ref:`options-linker`
312
313 .. tabularcolumns::
314     | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
315       p{\dimexpr 0.44\textwidth-2\tabcolsep} |
316       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
317       p{\dimexpr 0.10\textwidth-2\tabcolsep} |
318
319 .. flag-print::
320     :type: table
321     :category: linking
322
323 Plugin options
324 --------------
325
326 More details in :ref:`compiler-plugins`
327
328 .. tabularcolumns::
329     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
330       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
331       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
332       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
333
334 .. flag-print::
335     :type: table
336     :category: plugins
337
338 Replacing phases
339 ----------------
340
341 More details in :ref:`replacing-phases`
342
343 .. tabularcolumns::
344     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
345       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
346       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
347       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
348
349 .. flag-print::
350     :type: table
351     :category: phase-programs
352
353 Forcing options to particular phases
354 ------------------------------------
355
356 More details in :ref:`forcing-options-through`
357
358 .. tabularcolumns::
359     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
360       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
361       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
362       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
363
364 .. flag-print::
365     :type: table
366     :category: phase-options
367
368 Platform-specific options
369 -------------------------
370
371 More details in :ref:`options-platform`
372
373 .. tabularcolumns::
374     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
375       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
376       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
377       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
378
379 .. flag-print::
380     :type: table
381     :category: platform-options
382
383 Compiler debugging options
384 --------------------------
385
386 More details in :ref:`options-debugging`
387
388 .. tabularcolumns::
389     | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
390       p{\dimexpr 0.44\textwidth-2\tabcolsep} |
391       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
392       p{\dimexpr 0.10\textwidth-2\tabcolsep} |
393
394 .. flag-print::
395     :type: table
396     :category: debugging
397
398 Miscellaneous compiler options
399 ------------------------------
400
401 .. tabularcolumns::
402     | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
403       p{\dimexpr 0.44\textwidth-2\tabcolsep} |
404       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
405       p{\dimexpr 0.10\textwidth-2\tabcolsep} |
406
407 .. flag-print::
408     :type: table
409     :category: misc