Make language extensions their own category in the documentation
[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
178 Language options
179 ----------------
180
181 Language options can be enabled either by a command-line option
182 ``-Xblah``, or by a ``{-# LANGUAGE blah #-}`` pragma in the file itself.
183 See :ref:`options-language`.
184
185
186 Warnings
187 --------
188
189 More details in :ref:`options-sanity`
190
191 .. tabularcolumns::
192     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
193       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
194       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
195       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
196
197 .. flag-print::
198     :type: table
199     :category: warnings
200
201 Optimisation levels
202 -------------------
203
204 These options are described in more detail in :ref:`options-optimise`.
205
206 See :ref:`options-f-compact` for a list of optimisations enabled on
207 level 1 and level 2.
208
209 .. tabularcolumns::
210     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
211       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
212       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
213       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
214
215 .. flag-print::
216     :type: table
217     :category: optimization-levels
218
219 .. _options-f-compact:
220
221 Individual optimisations
222 ------------------------
223
224 These options are described in more detail in :ref:`options-f`. If a
225 flag is implied by ``-O`` then it is also implied by ``-O2`` (unless
226 flag description explicitly says otherwise). If a flag is implied by
227 ``-O0`` only then the flag is not implied by ``-O`` and ``-O2``.
228
229 .. tabularcolumns::
230     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
231       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
232       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
233       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
234
235 .. flag-print::
236     :type: table
237     :category: optimization
238
239 Profiling options
240 -----------------
241
242 More details in :ref:`profiling`
243
244 .. tabularcolumns::
245     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
246       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
247       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
248       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
249
250 .. flag-print::
251     :type: table
252     :category: profiling
253
254 Program coverage options
255 ------------------------
256
257 More details in :ref:`hpc`
258
259 .. tabularcolumns::
260     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
261       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
262       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
263       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
264
265 .. flag-print::
266     :type: table
267     :category: coverage
268
269 C pre-processor options
270 -----------------------
271
272 More details in :ref:`c-pre-processor`
273
274 .. tabularcolumns::
275     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
276       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
277       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
278       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
279
280 .. flag-print::
281     :type: table
282     :category: cpp
283
284 Code generation options
285 -----------------------
286
287 More details in :ref:`options-codegen`
288
289 .. tabularcolumns::
290     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
291       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
292       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
293       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
294
295 .. flag-print::
296     :type: table
297     :category: codegen
298
299 Linking options
300 ---------------
301
302 More details in :ref:`options-linker`
303
304 .. tabularcolumns::
305     | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
306       p{\dimexpr 0.44\textwidth-2\tabcolsep} |
307       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
308       p{\dimexpr 0.10\textwidth-2\tabcolsep} |
309
310 .. flag-print::
311     :type: table
312     :category: linking
313
314 Plugin options
315 --------------
316
317 More details in :ref:`compiler-plugins`
318
319 .. tabularcolumns::
320     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
321       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
322       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
323       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
324
325 .. flag-print::
326     :type: table
327     :category: plugins
328
329 Replacing phases
330 ----------------
331
332 More details in :ref:`replacing-phases`
333
334 .. tabularcolumns::
335     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
336       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
337       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
338       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
339
340 .. flag-print::
341     :type: table
342     :category: phase-programs
343
344 Forcing options to particular phases
345 ------------------------------------
346
347 More details in :ref:`forcing-options-through`
348
349 .. tabularcolumns::
350     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
351       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
352       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
353       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
354
355 .. flag-print::
356     :type: table
357     :category: phase-options
358
359 Platform-specific options
360 -------------------------
361
362 More details in :ref:`options-platform`
363
364 .. tabularcolumns::
365     | p{\dimexpr 0.30\textwidth-2\tabcolsep} |
366       p{\dimexpr 0.31\textwidth-2\tabcolsep} |
367       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
368       p{\dimexpr 0.29\textwidth-2\tabcolsep} |
369
370 .. flag-print::
371     :type: table
372     :category: platform-options
373
374 Compiler debugging options
375 --------------------------
376
377 More details in :ref:`options-debugging`
378
379 .. tabularcolumns::
380     | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
381       p{\dimexpr 0.44\textwidth-2\tabcolsep} |
382       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
383       p{\dimexpr 0.10\textwidth-2\tabcolsep} |
384
385 .. flag-print::
386     :type: table
387     :category: debugging
388
389 Miscellaneous compiler options
390 ------------------------------
391
392 .. tabularcolumns::
393     | p{\dimexpr 0.35\textwidth-2\tabcolsep} |
394       p{\dimexpr 0.44\textwidth-2\tabcolsep} |
395       p{\dimexpr 0.11\textwidth-2\tabcolsep} |
396       p{\dimexpr 0.10\textwidth-2\tabcolsep} |
397
398 .. flag-print::
399     :type: table
400     :category: misc