fe3c8cb58c5d0cf7c87cc657a6a9288cd1a3377a
[ghc.git] / docs / users_guide / using-warnings.rst
1 .. _options-sanity:
2
3 Warnings and sanity-checking
4 ----------------------------
5
6 .. index::
7    single: sanity-checking options
8    single: warnings
9
10 GHC has a number of options that select which types of non-fatal error
11 messages, otherwise known as warnings, can be generated during compilation.
12 Some options control individual warnings and others control collections
13 of warnings.
14 To turn off an individual warning ``-W<wflag>``, use ``-Wno-<wflag>``.
15 To reverse``-Werror``, which makes all warnings into errors, use ``-Wwarn``.
16
17 By default, you get a standard set of warnings which are
18 generally likely to indicate bugs in your program. These are:
19
20 .. hlist::
21     :columns: 3
22
23     * :ghc-flag:`-Woverlapping-patterns`
24     * :ghc-flag:`-Wwarnings-deprecations`
25     * :ghc-flag:`-Wdeprecations`
26     * :ghc-flag:`-Wdeprecated-flags`
27     * :ghc-flag:`-Wunrecognised-pragmas`
28     * :ghc-flag:`-Wduplicate-exports`
29     * :ghc-flag:`-Woverflowed-literals`
30     * :ghc-flag:`-Wempty-enumerations`
31     * :ghc-flag:`-Wmissing-fields`
32     * :ghc-flag:`-Wmissing-methods`
33     * :ghc-flag:`-Wwrong-do-bind`
34     * :ghc-flag:`-Wsimplifiable-class-constraints`
35     * :ghc-flag:`-Wtyped-holes`
36     * :ghc-flag:`-Wdeferred-type-errors`
37     * :ghc-flag:`-Wpartial-type-signatures`
38     * :ghc-flag:`-Wunsupported-calling-conventions`
39     * :ghc-flag:`-Wdodgy-foreign-imports`
40     * :ghc-flag:`-Winline-rule-shadowing`
41     * :ghc-flag:`-Wunsupported-llvm-version`
42     * :ghc-flag:`-Wtabs`
43     * :ghc-flag:`-Wunrecognised-warning-flags`
44     * :ghc-flag:`-Winaccessible-code`
45     * :ghc-flag:`-Wstar-is-type`
46     * :ghc-flag:`-Wstar-binder`
47     * :ghc-flag:`-Wspace-after-bang`
48
49 The following flags are simple ways to select standard "packages" of warnings:
50
51 .. ghc-flag:: -W
52     :shortdesc: enable normal warnings
53     :type: dynamic
54     :reverse: -w
55     :category:
56
57     Provides the standard warnings plus
58
59     .. hlist::
60         :columns: 3
61
62         * :ghc-flag:`-Wunused-binds`
63         * :ghc-flag:`-Wunused-matches`
64         * :ghc-flag:`-Wunused-foralls`
65         * :ghc-flag:`-Wunused-imports`
66         * :ghc-flag:`-Wincomplete-patterns`
67         * :ghc-flag:`-Wdodgy-exports`
68         * :ghc-flag:`-Wdodgy-imports`
69         * :ghc-flag:`-Wunbanged-strict-patterns`
70
71 .. ghc-flag:: -Wall
72     :shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
73     :type: dynamic
74     :reverse: -w
75     :category:
76
77     Turns on all warning options that indicate potentially suspicious
78     code. The warnings that are *not* enabled by :ghc-flag:`-Wall` are
79
80     .. hlist::
81         :columns: 3
82
83         * :ghc-flag:`-Wincomplete-uni-patterns`
84         * :ghc-flag:`-Wincomplete-record-updates`
85         * :ghc-flag:`-Wmonomorphism-restriction`
86         * :ghc-flag:`-Wimplicit-prelude`
87         * :ghc-flag:`-Wmissing-local-signatures`
88         * :ghc-flag:`-Wmissing-exported-signatures`
89         * :ghc-flag:`-Wmissing-export-lists`
90         * :ghc-flag:`-Wmissing-import-lists`
91         * :ghc-flag:`-Wmissing-home-modules`
92         * :ghc-flag:`-Widentities`
93         * :ghc-flag:`-Wredundant-constraints`
94         * :ghc-flag:`-Wpartial-fields`
95         * :ghc-flag:`-Wmissed-specialisations`
96         * :ghc-flag:`-Wall-missed-specialisations`
97
98 .. ghc-flag:: -Weverything
99     :shortdesc: enable all warnings supported by GHC
100     :type: dynamic
101     :category:
102
103     Turns on every single warning supported by the compiler.
104
105 .. ghc-flag:: -Wcompat
106     :shortdesc: enable future compatibility warnings
107         (details in :ref:`options-sanity`)
108     :type: dynamic
109     :reverse: -Wno-compat
110     :category:
111
112     Turns on warnings that will be enabled by default in the future, but remain
113     off in normal compilations for the time being. This allows library authors
114     eager to make their code future compatible to adapt to new features before
115     they even generate warnings.
116
117     This currently enables
118
119     .. hlist::
120         :columns: 3
121
122         * :ghc-flag:`-Wmissing-monadfail-instances`
123         * :ghc-flag:`-Wsemigroup`
124         * :ghc-flag:`-Wnoncanonical-monoid-instances`
125         * :ghc-flag:`-Wimplicit-kind-vars`
126         * :ghc-flag:`-Wstar-is-type`
127
128 .. ghc-flag:: -Wno-compat
129     :shortdesc: Disables all warnings enabled by :ghc-flag:`-Wcompat`.
130     :type: dynamic
131     :reverse: -Wcompat
132     :category:
133
134     Disables all warnings enabled by :ghc-flag:`-Wcompat`.
135
136 .. ghc-flag:: -w
137     :shortdesc: disable all warnings
138     :type: dynamic
139     :category:
140
141     Turns off all warnings, including the standard ones and those that
142     :ghc-flag:`-Wall` doesn't enable.
143
144 These options control which warnings are considered fatal and cause compilation
145 to abort.
146
147 .. ghc-flag:: -Werror
148     :shortdesc: make warnings fatal
149     :type: dynamic
150     :reverse: -Wwarn
151     :category:
152
153     Makes any warning into a fatal error. Useful so that you don't miss
154     warnings when doing batch compilation. To reverse ``-Werror`` and stop
155     treating any warnings as errors use ``-Wwarn``, or use ``-Wwarn=<wflag>``
156     to stop treating specific warnings as errors.
157
158 .. ghc-flag:: -Werror=⟨wflag⟩
159     :shortdesc: make a specific warning fatal
160     :type: dynamic
161     :reverse: -Wwarn=⟨wflag⟩
162     :category:
163     :noindex:
164
165     :implies: ``-W<wflag>``
166
167     Makes a specific warning into a fatal error. The warning will be enabled if
168     it hasn't been enabled yet. Can be reversed with ``-Wwarn=<wflag>``.
169
170     ``-Werror=compat`` has the same effect as ``-Werror=...`` for each warning
171     flag in the :ghc-flag:`-Wcompat` option group.
172
173 .. ghc-flag:: -Wwarn
174     :shortdesc: make warnings non-fatal
175     :type: dynamic
176     :reverse: -Werror
177     :category:
178
179     Warnings are treated only as warnings, not as errors. This is the
180     default, but can be useful to negate a :ghc-flag:`-Werror` flag.
181
182 .. ghc-flag:: -Wwarn=⟨wflag⟩
183     :shortdesc: make a specific warning non-fatal
184     :type: dynamic
185     :reverse: -Werror=⟨wflag⟩
186     :category:
187     :noindex:
188
189     Causes a specific warning to be treated as normal warning, not fatal error.
190
191     Note that it doesn't fully negate the effects of ``-Werror=<wflag>`` - the
192     warning will still be enabled.
193
194     ``-Wwarn=compat`` has the same effect as ``-Wwarn=...`` for each warning
195     flag in the :ghc-flag:`-Wcompat` option group.
196
197 When a warning is emitted, the specific warning flag which controls
198 it is shown.
199
200 .. ghc-flag:: -fshow-warning-groups
201     :shortdesc: show which group an emitted warning belongs to.
202     :type: dynamic
203     :reverse: -fno-show-warning-groups
204     :category:
205
206     When showing which flag controls a warning, also show the
207     respective warning group flag(s) that warning is contained in.
208
209     This option is off by default.
210
211 The full set of warning options is described below. To turn off any
212 warning, simply give the corresponding ``-Wno-...`` option on the
213 command line. For backwards compatibility with GHC versions prior to 8.0,
214 all these warnings can still be controlled with ``-f(no-)warn-*`` instead
215 of ``-W(no-)*``.
216
217 .. ghc-flag:: -Wunrecognised-warning-flags
218     :shortdesc: throw a warning when an unreconised ``-W...`` flag is
219         encountered on the command line.
220     :type: dynamic
221     :reverse: -Wno-unrecognised-warning-flags
222     :category:
223
224     Enables warnings when the compiler encounters a ``-W...`` flag that is not
225     recognised.
226
227     This warning is on by default.
228
229 .. ghc-flag:: -Wtyped-holes
230     :shortdesc: Report warnings when :ref:`typed hole <typed-holes>` errors are
231         :ref:`deferred until runtime <defer-type-errors>`. See
232         :ghc-flag:`-fdefer-typed-holes`.
233     :type: dynamic
234     :reverse: -Wno-typed-holes
235     :category:
236
237     Determines whether the compiler reports typed holes warnings. Has no
238     effect unless typed holes errors are deferred until runtime. See
239     :ref:`typed-holes` and :ref:`defer-type-errors`
240
241     This warning is on by default.
242
243 .. ghc-flag:: -Wdeferred-type-errors
244     :shortdesc: Report warnings when :ref:`deferred type errors
245         <defer-type-errors>` are enabled. This option is enabled by
246         default. See :ghc-flag:`-fdefer-type-errors`.
247     :type: dynamic
248     :reverse: -Wno-deferred-type-errors
249     :category:
250
251     Causes a warning to be reported when a type error is deferred until
252     runtime. See :ref:`defer-type-errors`
253
254     This warning is on by default.
255
256 .. ghc-flag:: -fdefer-type-errors
257     :shortdesc: Turn type errors into warnings, :ref:`deferring the error until
258         runtime <defer-type-errors>`. Implies
259         :ghc-flag:`-fdefer-typed-holes` and
260         :ghc-flag:`-fdefer-out-of-scope-variables`.
261         See also :ghc-flag:`-Wdeferred-type-errors`
262     :type: dynamic
263     :reverse: -fno-defer-type-errors
264     :category:
265
266     :implies: :ghc-flag:`-fdefer-typed-holes`, :ghc-flag:`-fdefer-out-of-scope-variables`
267
268     Defer as many type errors as possible until runtime. At compile time
269     you get a warning (instead of an error). At runtime, if you use a
270     value that depends on a type error, you get a runtime error; but you
271     can run any type-correct parts of your code just fine. See
272     :ref:`defer-type-errors`
273
274 .. ghc-flag:: -fdefer-typed-holes
275     :shortdesc: Convert :ref:`typed hole <typed-holes>` errors into warnings,
276         :ref:`deferring the error until runtime <defer-type-errors>`.
277         Implied by :ghc-flag:`-fdefer-type-errors`.
278         See also :ghc-flag:`-Wtyped-holes`.
279     :type: dynamic
280     :reverse: -fno-defer-typed-holes
281     :category:
282
283     Defer typed holes errors (errors about names with a leading underscore
284     (e.g., “_”, “_foo”, “_bar”)) until runtime. This will turn the errors
285     produced by :ref:`typed holes <typed-holes>` into warnings. Using a value
286     that depends on a typed hole produces a runtime error, the same as
287     :ghc-flag:`-fdefer-type-errors` (which implies this option). See :ref:`typed-holes`
288     and :ref:`defer-type-errors`.
289
290     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
291
292 .. ghc-flag:: -fdefer-out-of-scope-variables
293     :shortdesc: Convert variable out of scope variables errors into warnings.
294         Implied by :ghc-flag:`-fdefer-type-errors`.
295         See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
296     :type: dynamic
297     :reverse: -fno-defer-out-of-scope-variables
298     :category:
299
300     Defer variable out-of-scope errors (errors about names without a leading underscore)
301     until runtime. This will turn variable-out-of-scope errors into warnings.
302     Using a value that depends on an out-of-scope variable produces a runtime error,
303     the same as :ghc-flag:`-fdefer-type-errors` (which implies this option).
304     See :ref:`typed-holes` and :ref:`defer-type-errors`.
305
306     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
307
308 .. ghc-flag:: -Wdeferred-out-of-scope-variables
309     :shortdesc: Report warnings when variable out-of-scope errors are
310         :ref:`deferred until runtime <defer-type-errors>`.
311         See :ghc-flag:`-fdefer-out-of-scope-variables`.
312     :type: dynamic
313     :reverse: -Wno-deferred-out-of-scope-variables
314     :category:
315
316     Warn when a deferred out-of-scope variable is encountered.
317
318 .. ghc-flag:: -Wpartial-type-signatures
319     :shortdesc: warn about holes in partial type signatures when
320         :ghc-flag:`-XPartialTypeSignatures` is enabled. Not applicable when
321         :ghc-flag:`-XPartialTypesignatures` is not enabled, in which case
322         errors are generated for such holes. See
323         :ref:`partial-type-signatures`.
324     :type: dynamic
325     :reverse: -Wno-partial-type-signatures
326     :category:
327
328     Determines whether the compiler reports holes in partial type
329     signatures as warnings. Has no effect unless
330     :ghc-flag:`-XPartialTypeSignatures` is enabled, which controls whether
331     errors should be generated for holes in types or not. See
332     :ref:`partial-type-signatures`.
333
334     This warning is on by default.
335
336 .. ghc-flag:: -fhelpful-errors
337     :shortdesc: Make suggestions for mis-spelled names.
338     :type: dynamic
339     :reverse: -fno-helpful-errors
340     :category:
341
342     When a name or package is not found in scope, make suggestions for
343     the name or package you might have meant instead.
344
345     This option is on by default.
346
347 .. ghc-flag:: -Wunrecognised-pragmas
348     :shortdesc: warn about uses of pragmas that GHC doesn't recognise
349     :type: dynamic
350     :reverse: -Wno-unrecognised-pragmas
351     :category:
352
353     Causes a warning to be emitted when a pragma that GHC doesn't
354     recognise is used. As well as pragmas that GHC itself uses, GHC also
355     recognises pragmas known to be used by other tools, e.g.
356     ``OPTIONS_HUGS`` and ``DERIVE``.
357
358     This option is on by default.
359
360 .. ghc-flag:: -Wmissed-specialisations
361     :shortdesc: warn when specialisation of an imported, overloaded function
362         fails.
363     :type: dynamic
364     :reverse: -Wno-missed-specialisations
365     :category:
366
367     Emits a warning if GHC cannot specialise an overloaded function, usually
368     because the function needs an ``INLINABLE`` pragma. Reports when the
369     situation arises during specialisation of an imported function.
370
371     This form is intended to catch cases where an imported function
372     that is marked as ``INLINABLE`` (presumably to enable specialisation)
373     cannot be specialised as it calls other functions that are themselves not
374     specialised.
375
376     Note that this warning will not throw errors if used with
377     :ghc-flag:`-Werror`.
378
379     This option is off by default.
380
381 .. ghc-flag:: -Wall-missed-specialisations
382     :shortdesc: warn when specialisation of any overloaded function fails.
383     :type: dynamic
384     :reverse: -Wno-all-missed-specialisations
385     :category:
386
387     Emits a warning if GHC cannot specialise an overloaded function, usually
388     because the function needs an ``INLINABLE`` pragma. Reports
389     all such situations.
390
391     Note that this warning will not throw errors if used with
392     :ghc-flag:`-Werror`.
393
394     This option is off by default.
395
396 .. ghc-flag:: -Wwarnings-deprecations
397     :shortdesc: warn about uses of functions & types that have warnings or
398         deprecated pragmas
399     :type: dynamic
400     :reverse: -Wno-warnings-deprecations
401     :category:
402
403     .. index::
404        pair: deprecations; warnings
405
406     Causes a warning to be emitted when a module, function or type with
407     a ``WARNING`` or ``DEPRECATED pragma`` is used. See
408     :ref:`warning-deprecated-pragma` for more details on the pragmas.
409
410     This option is on by default.
411
412 .. ghc-flag:: -Wdeprecations
413     :shortdesc: warn about uses of functions & types that have warnings or
414         deprecated pragmas. Alias for :ghc-flag:`-Wwarnings-deprecations`
415     :type: dynamic
416     :reverse: -Wno-deprecations
417     :category:
418
419     .. index::
420        single: deprecations
421
422     Causes a warning to be emitted when a module, function or type with
423     a ``WARNING`` or ``DEPRECATED pragma`` is used. See
424     :ref:`warning-deprecated-pragma` for more details on the pragmas.
425     An alias for :ghc-flag:`-Wwarnings-deprecations`.
426
427     This option is on by default.
428
429 .. ghc-flag:: -Wnoncanonical-monad-instances
430     :shortdesc: warn when ``Applicative`` or ``Monad`` instances have
431         noncanonical definitions of ``return``, ``pure``, ``(>>)``,
432         or ``(*>)``.
433         See flag description in :ref:`options-sanity` for more details.
434     :type: dynamic
435     :reverse: -Wno-noncanonical-monad-instances
436     :category:
437
438     Warn if noncanonical ``Applicative`` or ``Monad`` instances
439     declarations are detected.
440
441     When this warning is enabled, the following conditions are verified:
442
443     In ``Monad`` instances declarations warn if any of the following
444     conditions does not hold:
445
446      * If ``return`` is defined it must be canonical (i.e. ``return = pure``).
447      * If ``(>>)`` is defined it must be canonical (i.e. ``(>>) = (*>)``).
448
449     Moreover, in ``Applicative`` instance declarations:
450
451      * Warn if ``pure`` is defined backwards (i.e. ``pure = return``).
452      * Warn if ``(*>)`` is defined backwards (i.e. ``(*>) = (>>)``).
453
454     This option is off by default.
455
456 .. ghc-flag:: -Wnoncanonical-monadfail-instances
457     :shortdesc: warn when ``Monad`` or ``MonadFail`` instances have
458         noncanonical definitions of ``fail``.
459         See flag description in :ref:`options-sanity` for more details.
460     :type: dynamic
461     :reverse: -Wno-noncanonical-monadfail-instances
462     :category:
463
464     Warn if noncanonical ``Monad`` or ``MonadFail`` instances
465     declarations are detected.
466
467     When this warning is enabled, the following conditions are verified:
468
469     In ``Monad`` instances declarations warn if any of the following
470     conditions does not hold:
471
472      * If ``fail`` is defined it must be canonical
473        (i.e. ``fail = Control.Monad.Fail.fail``).
474
475     Moreover, in ``MonadFail`` instance declarations:
476
477      * Warn if ``fail`` is defined backwards
478        (i.e. ``fail = Control.Monad.fail``).
479
480     See also :ghc-flag:`-Wmissing-monadfail-instances`.
481
482     This option is off by default.
483
484 .. ghc-flag:: -Wnoncanonical-monoid-instances
485     :shortdesc: warn when ``Semigroup`` or ``Monoid`` instances have
486         noncanonical definitions of ``(<>)`` or ``mappend``.
487         See flag description in :ref:`options-sanity` for more details.
488     :type: dynamic
489     :reverse: -Wno-noncanonical-monoid-instances
490     :category:
491
492     Warn if noncanonical ``Semigroup`` or ``Monoid`` instances
493     declarations are detected.
494
495     When this warning is enabled, the following conditions are verified:
496
497     In ``Monoid`` instances declarations warn if any of the following
498     conditions does not hold:
499
500      * If ``mappend`` is defined it must be canonical
501        (i.e. ``mappend = (Data.Semigroup.<>)``).
502
503     Moreover, in ``Semigroup`` instance declarations:
504
505      * Warn if ``(<>)`` is defined backwards (i.e. ``(<>) = mappend``).
506
507     This warning is off by default. However, it is part of the
508     :ghc-flag:`-Wcompat` option group.
509
510 .. ghc-flag:: -Wmissing-monadfail-instances
511     :shortdesc: Warn when a failable pattern is used in a do-block that does
512         not have a ``MonadFail`` instance.
513     :type: dynamic
514     :reverse: -Wno-missing-monadfail-instances
515     :category:
516
517     .. index::
518        single: MFP
519        single: MonadFail Proposal
520
521     Warn when a failable pattern is used in a do-block that does not have a
522     ``MonadFail`` instance.
523
524     See also :ghc-flag:`-Wnoncanonical-monadfail-instances`.
525
526     Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
527     default, but will be switched on in a future GHC release, as part of
528     the `MonadFail Proposal (MFP)
529     <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
530
531 .. ghc-flag:: -Wsemigroup
532     :shortdesc: warn when a ``Monoid`` is not ``Semigroup``, and on non-
533         ``Semigroup`` definitions of ``(<>)``?
534     :type: dynamic
535     :reverse: -Wno-semigroup
536     :category:
537
538     .. index::
539        single: semigroup; warning
540
541     Warn when definitions are in conflict with the future inclusion of
542     ``Semigroup`` into the standard typeclasses.
543
544      1. Instances of ``Monoid`` should also be instances of ``Semigroup``
545      2. The ``Semigroup`` operator ``(<>)`` will be in ``Prelude``, which
546         clashes with custom local definitions of such an operator
547
548     Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
549     default, but will be switched on in a future GHC release.
550
551 .. ghc-flag:: -Wdeprecated-flags
552     :shortdesc: warn about uses of commandline flags that are deprecated
553     :type: dynamic
554     :reverse: -Wno-deprecated-flags
555     :category:
556
557     .. index::
558        single: deprecated flags
559
560     Causes a warning to be emitted when a deprecated command-line flag
561     is used.
562
563     This option is on by default.
564
565 .. ghc-flag:: -Wunsupported-calling-conventions
566     :shortdesc: warn about use of an unsupported calling convention
567     :type: dynamic
568     :reverse: -Wno-unsupported-calling-conventions
569     :category:
570
571     Causes a warning to be emitted for foreign declarations that use
572     unsupported calling conventions. In particular, if the ``stdcall``
573     calling convention is used on an architecture other than i386 then
574     it will be treated as ``ccall``.
575
576 .. ghc-flag:: -Wdodgy-foreign-imports
577     :shortdesc: warn about dodgy foreign imports
578     :type: dynamic
579     :reverse: -Wno-dodgy-foreign-import
580     :category:
581
582     Causes a warning to be emitted for foreign imports of the following
583     form: ::
584
585         foreign import "f" f :: FunPtr t
586
587     on the grounds that it probably should be ::
588
589         foreign import "&f" f :: FunPtr t
590
591     The first form declares that ``f`` is a (pure) C function that takes
592     no arguments and returns a pointer to a C function with type ``t``,
593     whereas the second form declares that ``f`` itself is a C function
594     with type ``t``. The first declaration is usually a mistake, and one
595     that is hard to debug because it results in a crash, hence this
596     warning.
597
598 .. ghc-flag:: -Wdodgy-exports
599     :shortdesc: warn about dodgy exports
600     :type: dynamic
601     :reverse: -Wno-dodgy-exports
602     :category:
603
604     Causes a warning to be emitted when a datatype ``T`` is exported
605     with all constructors, i.e. ``T(..)``, but is it just a type
606     synonym.
607
608     Also causes a warning to be emitted when a module is re-exported,
609     but that module exports nothing.
610
611 .. ghc-flag:: -Wdodgy-imports
612     :shortdesc: warn about dodgy imports
613     :type: dynamic
614     :reverse: -Wno-dodgy-imports
615     :category:
616
617     Causes a warning to be emitted in the following cases:
618
619     -  When a datatype ``T`` is imported with all constructors, i.e.
620        ``T(..)``, but has been exported abstractly, i.e. ``T``.
621
622     -  When an ``import`` statement hides an entity that is not
623        exported.
624
625 .. ghc-flag:: -Woverflowed-literals
626     :shortdesc: warn about literals that will overflow their type
627     :type: dynamic
628     :reverse: -Wno-overflowed-literals
629     :category:
630
631     Causes a warning to be emitted if a literal will overflow, e.g.
632     ``300 :: Word8``.
633
634 .. ghc-flag:: -Wempty-enumerations
635     :shortdesc: warn about enumerations that are empty
636     :type: dynamic
637     :reverse: -Wno-empty-enumerations
638     :category:
639
640     Causes a warning to be emitted if an enumeration is empty, e.g.
641     ``[5 .. 3]``.
642
643 .. ghc-flag:: -Wduplicate-constraints
644     :shortdesc: warn when a constraint appears duplicated in a type signature
645     :type: dynamic
646     :reverse: -Wno-duplicate-constraints
647     :category:
648
649     .. index::
650        single: duplicate constraints, warning
651
652     Have the compiler warn about duplicate constraints in a type
653     signature. For example ::
654
655         f :: (Eq a, Show a, Eq a) => a -> a
656
657     The warning will indicate the duplicated ``Eq a`` constraint.
658
659     This option is now deprecated in favour of
660     :ghc-flag:`-Wredundant-constraints`.
661
662 .. ghc-flag:: -Wredundant-constraints
663     :shortdesc: Have the compiler warn about redundant constraints in type
664         signatures.
665     :type: dynamic
666     :reverse: -Wno-redundant-constraints
667     :category:
668
669     :since: 8.0
670
671     .. index::
672        single: redundant constraints, warning
673
674     Have the compiler warn about redundant constraints in a type
675     signature. In particular:
676
677     -  A redundant constraint within the type signature itself: ::
678
679             f :: (Eq a, Ord a) => a -> a
680
681        The warning will indicate the redundant ``Eq a`` constraint: it
682        is subsumed by the ``Ord a`` constraint.
683
684     -  A constraint in the type signature is not used in the code it
685        covers: ::
686
687             f :: Eq a => a -> a -> Bool
688             f x y = True
689
690        The warning will indicate the redundant ``Eq a`` constraint: : it
691        is not used by the definition of ``f``.)
692
693     Similar warnings are given for a redundant constraint in an instance
694     declaration.
695
696     When turning on, you can suppress it on a per-module basis with
697     :ghc-flag:`-Wno-redundant-constraints <-Wredundant-constraints>`.
698     Occasionally you may specifically want a function to have a more
699     constrained signature than necessary, perhaps to leave yourself
700     wiggle-room for changing the implementation without changing the
701     API. In that case, you can suppress the warning on a per-function
702     basis, using a call in a dead binding. For example: ::
703
704         f :: Eq a => a -> a -> Bool
705         f x y = True
706         where
707             _ = x == x  -- Suppress the redundant-constraint warning for (Eq a)
708
709     Here the call to ``(==)`` makes GHC think that the ``(Eq a)``
710     constraint is needed, so no warning is issued.
711
712 .. ghc-flag:: -Wduplicate-exports
713     :shortdesc: warn when an entity is exported multiple times
714     :type: dynamic
715     :reverse: -Wno-duplicate-exports
716     :category:
717
718     .. index::
719        single: duplicate exports, warning
720        single: export lists, duplicates
721
722     Have the compiler warn about duplicate entries in export lists. This
723     is useful information if you maintain large export lists, and want
724     to avoid the continued export of a definition after you've deleted
725     (one) mention of it in the export list.
726
727     This option is on by default.
728
729 .. ghc-flag:: -Whi-shadowing
730     :shortdesc: warn when a ``.hi`` file in the current directory shadows a library
731     :type: dynamic
732     :reverse: -Wno-hi-shadowing
733     :category:
734
735     .. index::
736        single: shadowing; interface files
737
738     Causes the compiler to emit a warning when a module or interface
739     file in the current directory is shadowing one with the same module
740     name in a library or other directory.
741
742 .. ghc-flag:: -Widentities
743     :shortdesc: warn about uses of Prelude numeric conversions that are probably
744         the identity (and hence could be omitted)
745     :type: dynamic
746     :reverse: -Wno-identities
747     :category:
748
749     Causes the compiler to emit a warning when a Prelude numeric
750     conversion converts a type ``T`` to the same type ``T``; such calls are
751     probably no-ops and can be omitted. The functions checked for are:
752     ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.
753
754 .. ghc-flag:: -Wimplicit-prelude
755     :shortdesc: warn when the Prelude is implicitly imported
756     :type: dynamic
757     :reverse: -Wno-implicit-prelude
758     :category:
759
760     .. index::
761        single: implicit prelude, warning
762
763     Have the compiler warn if the Prelude is implicitly imported. This happens
764     unless either the Prelude module is explicitly imported with an ``import
765     ... Prelude ...`` line, or this implicit import is disabled (either by
766     :ghc-flag:`-XNoImplicitPrelude` or a ``LANGUAGE NoImplicitPrelude``
767     pragma).
768
769     Note that no warning is given for syntax that implicitly refers to the
770     Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
771     refers to the Prelude. For example, no warning is given when ``368`` means
772     ``Prelude.fromInteger (368::Prelude.Integer)`` (where ``Prelude`` refers
773     to the actual Prelude module, regardless of the imports of the module
774     being compiled).
775
776     This warning is off by default.
777
778 .. ghc-flag:: -Wimplicit-kind-vars
779     :shortdesc: warn when kind variables are brought into scope implicitly despite
780         the "forall-or-nothing" rule
781     :type: dynamic
782     :reverse: -Wno-implicit-kind-vars
783     :category:
784
785     :since: 8.6
786
787     `GHC proposal #24
788     <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0024-no-kind-vars.rst>`__
789     prescribes to treat kind variables and type variables identically in
790     ``forall``, removing the legacy distinction between them.
791
792     Consider the following examples: ::
793
794         f :: Proxy a -> Proxy b -> ()
795         g :: forall a b. Proxy a -> Proxy b -> ()
796
797     ``f`` does not use an explicit ``forall``, so type variables ``a`` and ``b``
798     are brought into scope implicitly. ``g`` quantifies both ``a`` and ``b``
799     explicitly. Both ``f`` and ``g`` work today and will continue to work in the
800     future because they adhere to the "forall-or-nothing" rule: either all type
801     variables in a function definition are introduced explicitly or implicitly,
802     there is no middle ground.
803
804     A violation of the "forall-or-nothing" rule looks like this: ::
805
806         m :: forall a. Proxy a -> Proxy b -> ()
807
808     ``m`` does not introduce one of the variables, ``b``, and thus is rejected.
809
810     However, consider the following example: ::
811
812         n :: forall a. Proxy (a :: k) -> ()
813
814     While ``n`` uses ``k`` without introducing it and thus violates the rule, it
815     is currently accepted. This is because ``k`` in ``n`` is considered a kind
816     variable, as it occurs in a kind signature. In reality, the line between
817     type variables and kind variables is blurry, as the following example
818     demonstrates: ::
819
820         kindOf :: forall a. Proxy (a :: k) -> Proxy k
821
822     In ``kindOf``, the ``k`` variable is used both in a kind position and a type
823     position. Currently, ``kindOf`` happens to be accepted as well.
824
825     In a future release of GHC, both ``n`` and ``kindOf`` will be rejected per
826     the "forall-or-nothing" rule. This warning, being part of the
827     :ghc-flag:`-Wcompat` option group, allows to detect this before the actual
828     breaking change takes place.
829
830 .. ghc-flag:: -Wincomplete-patterns
831     :shortdesc: warn when a pattern match could fail
832     :type: dynamic
833     :reverse: -Wno-incomplete-patterns
834     :category:
835
836     .. index::
837        single: incomplete patterns, warning
838        single: patterns, incomplete
839
840     The option :ghc-flag:`-Wincomplete-patterns` warns about places where a
841     pattern-match might fail at runtime. The function ``g`` below will
842     fail when applied to non-empty lists, so the compiler will emit a
843     warning about this when :ghc-flag:`-Wincomplete-patterns` is enabled. ::
844
845         g [] = 2
846
847     This option isn't enabled by default because it can be a bit noisy,
848     and it doesn't always indicate a bug in the program. However, it's
849     generally considered good practice to cover all the cases in your
850     functions, and it is switched on by :ghc-flag:`-W`.
851
852
853 .. ghc-flag:: -Wincomplete-uni-patterns
854     :shortdesc: warn when a pattern match in a lambda expression or
855         pattern binding could fail
856     :type: dynamic
857     :reverse: -Wno-incomplete-uni-patterns
858     :category:
859
860     The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar to
861     :ghc-flag:`-Wincomplete-patterns`, except that it applies only to
862     lambda-expressions and pattern bindings, constructs that only allow a
863     single pattern: ::
864
865         h = \[] -> 2
866         Just k = f y
867
868 .. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩
869     :shortdesc: the iteration limit for the pattern match checker
870     :type: dynamic
871     :category:
872
873     :default: 2000000
874
875     Sets how many iterations of the pattern-match checker will perform before
876     giving up. This limit is to catch cases where pattern-match checking might
877     be excessively costly (due to the exponential complexity of coverage
878     checking in the general case). It typically shouldn't be necessary to set
879     this unless GHC informs you that it has exceeded the pattern match checker's
880     iteration limit (in which case you may want to consider refactoring your
881     pattern match, for the sake of future readers of your code.
882
883 .. ghc-flag:: -Wincomplete-record-updates
884     :shortdesc: warn when a record update could fail
885     :type: dynamic
886     :reverse: -Wno-incomplete-record-updates
887     :category:
888
889     .. index::
890        single: incomplete record updates, warning
891        single: record updates, incomplete
892
893     The function ``f`` below will fail when applied to ``Bar``, so the
894     compiler will emit a warning about this when
895     :ghc-flag:`-Wincomplete-record-updates` is enabled. ::
896
897         data Foo = Foo { x :: Int }
898                  | Bar
899
900         f :: Foo -> Foo
901         f foo = foo { x = 6 }
902
903     This option isn't enabled by default because it can be very noisy,
904     and it often doesn't indicate a bug in the program.
905
906 .. ghc-flag:: -Wmissing-fields
907     :shortdesc: warn when fields of a record are uninitialised
908     :type: dynamic
909     :reverse: -Wno-missing-fields
910     :category:
911
912     .. index::
913        single: missing fields, warning
914        single: fields, missing
915
916     This option is on by default, and warns you whenever the
917     construction of a labelled field constructor isn't complete, missing
918     initialisers for one or more fields. While not an error (the missing
919     fields are initialised with bottoms), it is often an indication of a
920     programmer error.
921
922 .. ghc-flag:: -Wmissing-export-lists
923     :shortdesc: warn when a module declaration does not explicitly list all
924         exports
925     :type: dynamic
926     :reverse: -fnowarn-missing-export-lists
927     :category:
928
929     :since: 8.4.1
930
931     .. index::
932        single: missing export lists, warning
933        single: export lists, missing
934
935     This flag warns if you declare a module without declaring an explicit
936     export list. For example ::
937
938         module M where
939
940           p x = x
941
942     The :ghc-flag:`-Wmissing-export-lists` flag will warn that ``M`` does not
943     declare an export list. Declaring an explicit export list for ``M`` enables
944     GHC dead code analysis, prevents accidental export of names and can ease
945     optimizations like inlining.
946
947 .. ghc-flag:: -Wmissing-import-lists
948     :shortdesc: warn when an import declaration does not explicitly list all the
949         names brought into scope
950     :type: dynamic
951     :reverse: -fnowarn-missing-import-lists
952     :category:
953
954     .. index::
955        single: missing import lists, warning
956        single: import lists, missing
957
958     This flag warns if you use an unqualified ``import`` declaration
959     that does not explicitly list the entities brought into scope. For
960     example ::
961
962         module M where
963           import X( f )
964           import Y
965           import qualified Z
966           p x = f x x
967
968     The :ghc-flag:`-Wmissing-import-lists` flag will warn about the import of
969     ``Y`` but not ``X`` If module ``Y`` is later changed to export (say) ``f``,
970     then the reference to ``f`` in ``M`` will become ambiguous. No warning is
971     produced for the import of ``Z`` because extending ``Z``\'s exports would be
972     unlikely to produce ambiguity in ``M``.
973
974 .. ghc-flag:: -Wmissing-methods
975     :shortdesc: warn when class methods are undefined
976     :type: dynamic
977     :reverse: -Wno-missing-methods
978     :category:
979
980     .. index::
981        single: missing methods, warning
982        single: methods, missing
983
984     This option is on by default, and warns you whenever an instance
985     declaration is missing one or more methods, and the corresponding
986     class declaration has no default declaration for them.
987
988     The ``MINIMAL`` pragma can be used to change which combination of
989     methods will be required for instances of a particular class. See
990     :ref:`minimal-pragma`.
991
992 .. ghc-flag:: -Wmissing-signatures
993     :shortdesc: warn about top-level functions without signatures
994     :type: dynamic
995     :reverse: -Wno-missing-signatures
996     :category:
997
998     .. index::
999        single: type signatures, missing
1000
1001     If you would like GHC to check that every top-level function/value
1002     has a type signature, use the :ghc-flag:`-Wmissing-signatures` option.
1003     As part of the warning GHC also reports the inferred type. The
1004     option is off by default.
1005
1006 .. ghc-flag:: -Wmissing-exported-sigs
1007     :shortdesc: *(deprecated)*
1008         warn about top-level functions without signatures, only if they
1009         are exported. takes precedence over -Wmissing-signatures
1010     :type: dynamic
1011     :reverse: -Wno-missing-exported-sigs
1012     :category:
1013
1014     .. index::
1015        single: type signatures, missing
1016
1017     This option is now deprecated in favour of
1018     :ghc-flag:`-Wmissing-exported-signatures`.
1019
1020 .. ghc-flag:: -Wmissing-exported-signatures
1021     :shortdesc: warn about top-level functions without signatures, only if they
1022         are exported. takes precedence over -Wmissing-signatures
1023     :type: dynamic
1024     :reverse: -Wno-missing-exported-signatures
1025     :category:
1026
1027     .. index::
1028        single: type signatures, missing
1029
1030     If you would like GHC to check that every exported top-level
1031     function/value has a type signature, but not check unexported
1032     values, use the :ghc-flag:`-Wmissing-exported-signatures`
1033     option. This option takes precedence over
1034     :ghc-flag:`-Wmissing-signatures`. As part of the warning GHC also
1035     reports the inferred type. The option is off by default.
1036
1037 .. ghc-flag:: -Wmissing-local-sigs
1038     :shortdesc: *(deprecated)*
1039         warn about polymorphic local bindings without signatures
1040     :type: dynamic
1041     :reverse: -Wno-missing-local-sigs
1042     :category:
1043
1044     .. index::
1045        single: type signatures, missing
1046
1047     This option is now deprecated in favour of
1048     :ghc-flag:`-Wmissing-local-signatures`.
1049
1050 .. ghc-flag:: -Wmissing-local-signatures
1051     :shortdesc: warn about polymorphic local bindings without signatures
1052     :type: dynamic
1053     :reverse: -Wno-missing-local-signatures
1054     :category:
1055
1056     .. index::
1057        single: type signatures, missing
1058
1059     If you use the :ghc-flag:`-Wmissing-local-signatures` flag GHC
1060     will warn you about any polymorphic local bindings. As part of the
1061     warning GHC also reports the inferred type. The option is off by
1062     default.
1063
1064 .. ghc-flag:: -Wmissing-pattern-synonym-signatures
1065     :shortdesc: warn when pattern synonyms do not have type signatures
1066     :type: dynamic
1067     :reverse: -Wno-missing-pattern-synonym-signatures
1068     :category:
1069
1070     .. index::
1071          single: type signatures, missing, pattern synonyms
1072
1073     If you would like GHC to check that every pattern synonym has a
1074     type signature, use the
1075     :ghc-flag:`-Wmissing-pattern-synonym-signatures` option. If this
1076     option is used in conjunction with
1077     :ghc-flag:`-Wmissing-exported-signatures` then only exported pattern
1078     synonyms must have a type signature. GHC also reports the inferred
1079     type. This option is off by default.
1080
1081 .. ghc-flag:: -Wname-shadowing
1082     :shortdesc: warn when names are shadowed
1083     :type: dynamic
1084     :reverse: -Wno-name-shadowing
1085     :category:
1086
1087     .. index::
1088        single: shadowing, warning
1089
1090     This option causes a warning to be emitted whenever an inner-scope
1091     value has the same name as an outer-scope value, i.e. the inner
1092     value shadows the outer one. This can catch typographical errors
1093     that turn into hard-to-find bugs, e.g., in the inadvertent capture
1094     of what would be a recursive call in
1095     ``f = ... let f = id in ... f ...``.
1096
1097     The warning is suppressed for names beginning with an underscore.
1098     For example ::
1099
1100         f x = do { _ignore <- this; _ignore <- that; return (the other) }
1101
1102 .. ghc-flag:: -Worphans
1103     :shortdesc: warn when the module contains :ref:`orphan instance declarations
1104         or rewrite rules <orphan-modules>`
1105     :type: dynamic
1106     :reverse: -Wno-orphans
1107     :category:
1108
1109     .. index::
1110        single: orphan instances, warning
1111        single: orphan rules, warning
1112
1113     These flags cause a warning to be emitted whenever the module
1114     contains an "orphan" instance declaration or rewrite rule. An
1115     instance declaration is an orphan if it appears in a module in which
1116     neither the class nor the type being instanced are declared in the
1117     same module. A rule is an orphan if it is a rule for a function
1118     declared in another module. A module containing any orphans is
1119     called an orphan module.
1120
1121     The trouble with orphans is that GHC must pro-actively read the
1122     interface files for all orphan modules, just in case their instances
1123     or rules play a role, whether or not the module's interface would
1124     otherwise be of any use. See :ref:`orphan-modules` for details.
1125
1126     The flag :ghc-flag:`-Worphans` warns about user-written orphan rules or
1127     instances.
1128
1129 .. ghc-flag:: -Woverlapping-patterns
1130     :shortdesc: warn about overlapping patterns
1131     :type: dynamic
1132     :reverse: -Wno-overlapping-patterns
1133     :category:
1134
1135     .. index::
1136        single: overlapping patterns, warning
1137        single: patterns, overlapping
1138
1139     By default, the compiler will warn you if a set of patterns are
1140     overlapping, e.g., ::
1141
1142         f :: String -> Int
1143         f []     = 0
1144         f (_:xs) = 1
1145         f "2"    = 2
1146
1147     where the last pattern match in ``f`` won't ever be reached, as the
1148     second pattern overlaps it. More often than not, redundant patterns
1149     is a programmer mistake/error, so this option is enabled by default.
1150
1151 .. ghc-flag:: -Winaccessible-code
1152     :shortdesc: warn about inaccessible code
1153     :type: dynamic
1154     :reverse: -Wno-inaccessible-code
1155     :category:
1156
1157     .. index::
1158        single: inaccessible code, warning
1159        single: inaccessible
1160
1161     By default, the compiler will warn you if types make a branch inaccessible.
1162     This generally requires GADTs or similar extensions.
1163
1164     Take, for example, the following program ::
1165
1166         {-# LANGUAGE GADTs #-}
1167
1168         data Foo a where
1169          Foo1 :: Foo Char
1170          Foo2 :: Foo Int
1171
1172         data TyEquality a b where
1173                 Refl :: TyEquality a a
1174
1175         checkTEQ :: Foo t -> Foo u -> Maybe (TyEquality t u)
1176         checkTEQ x y = error "unimportant"
1177
1178         step2 :: Bool
1179         step2 = case checkTEQ Foo1 Foo2 of
1180                  Just Refl -> True -- Inaccessible code
1181                  Nothing -> False
1182
1183     The ``Just Refl`` case in ``step2`` is inaccessible, because in order for
1184     ``checkTEQ`` to be able to produce a ``Just``, ``t ~ u`` must hold, but
1185     since we're passing ``Foo1`` and ``Foo2`` here, it follows that ``t ~
1186     Char``, and ``u ~ Int``, and thus ``t ~ u`` cannot hold.
1187
1188 .. ghc-flag:: -Wstar-is-type
1189      :shortdesc: warn when ``*`` is used to mean ``Data.Kind.Type``
1190      :type: dynamic
1191      :reverse: -Wno-star-is-type
1192      :category:
1193
1194      :since: 8.6
1195
1196      The use of ``*`` to denote the kind of inhabited types relies on the
1197      :extension:`StarIsType` extension, which in a future release will be
1198      turned off by default and then possibly removed. The reasons for this and
1199      the deprecation schedule are described in `GHC proposal #30
1200      <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst>`__.
1201
1202      This warning allows to detect such uses of ``*`` before the actual
1203      breaking change takes place. The recommended fix is to replace ``*`` with
1204      ``Type`` imported from ``Data.Kind``.
1205
1206      Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
1207      default, but will be switched on in a future GHC release.
1208
1209 .. ghc-flag:: -Wstar-binder
1210      :shortdesc: warn about binding the ``(*)`` type operator despite
1211          :ghc-flag:`-XStarIsType`
1212      :type: dynamic
1213      :reverse: -Wno-star-binder
1214
1215      Under :ghc-flag:`-XStarIsType`, a ``*`` in types is not an operator nor
1216      even a name, it is special syntax that stands for ``Data.Kind.Type``. This
1217      means that an expression like ``Either * Char`` is parsed as ``Either (*)
1218      Char`` and not ``(*) Either Char``.
1219
1220      In binding positions, we have similar parsing rules. Consider the following
1221      example ::
1222
1223          {-# LANGUAGE TypeOperators, TypeFamilies, StarIsType #-}
1224
1225          type family a + b
1226          type family a * b
1227
1228      While ``a + b`` is parsed as ``(+) a b`` and becomes a binding position for
1229      the ``(+)`` type operator, ``a * b`` is parsed as ``a (*) b`` and is rejected.
1230
1231      As a workaround, we allow to bind ``(*)`` in prefix form::
1232
1233          type family (*) a b
1234
1235      This is a rather fragile arrangement, as generally a programmer expects
1236      ``(*) a b`` to be equivalent to ``a * b``. With :ghc-flag:`-Wstar-binder`
1237      we warn when this special treatment of ``(*)`` takes place.
1238
1239 .. ghc-flag:: -Wsimplifiable-class-constraints
1240     :shortdesc: Warn about class constraints in a type signature that can
1241         be simplified using a top-level instance declaration.
1242     :type: dynamic
1243     :reverse: -Wno-simplifiable-class-constraints
1244     :category:
1245
1246     :since: 8.2
1247
1248     .. index::
1249        single: simplifiable class constraints, warning
1250
1251     Warn about class constraints in a type signature that can be simplified
1252     using a top-level instance declaration.  For example: ::
1253
1254        f :: Eq [a] => a -> a
1255
1256     Here the ``Eq [a]`` in the signature overlaps with the top-level
1257     instance for ``Eq [a]``.  GHC goes to some efforts to use the former,
1258     but if it should use the latter, it would then have an
1259     insoluble ``Eq a`` constraint.  Best avoided by instead writing: ::
1260
1261        f :: Eq a => a -> a
1262
1263     This option is on by default. As usual you can suppress it on a
1264     per-module basis with :ghc-flag:`-Wno-simplifiable-class-constraints
1265     <-Wsimplifiable-class-constraints>`.
1266
1267 .. ghc-flag:: -Wspace-after-bang
1268      :shortdesc: warn for missing space before the second argument
1269         of an infix definition of ``(!)`` when
1270         :ghc-flag:`-XBangPatterns` are not enabled
1271      :type: dynamic
1272      :reverse: -Wno-missing-space-after-bang
1273 .. ghc-flag:: -Wtabs
1274     :shortdesc: warn if there are tabs in the source file
1275     :type: dynamic
1276     :reverse: -Wno-tabs
1277     :category:
1278
1279     .. index::
1280        single: tabs, warning
1281
1282     Have the compiler warn if there are tabs in your source file.
1283
1284 .. ghc-flag:: -Wtype-defaults
1285     :shortdesc: warn when defaulting happens
1286     :type: dynamic
1287     :reverse: -Wno-type-defaults
1288     :category:
1289
1290     .. index::
1291        single: defaulting mechanism, warning
1292
1293     Have the compiler warn/inform you where in your source the Haskell
1294     defaulting mechanism for numeric types kicks in. This is useful
1295     information when converting code from a context that assumed one
1296     default into one with another, e.g., the ‘default default’ for
1297     Haskell 1.4 caused the otherwise unconstrained value ``1`` to be
1298     given the type ``Int``, whereas Haskell 98 and later defaults it to
1299     ``Integer``. This may lead to differences in performance and
1300     behaviour, hence the usefulness of being non-silent about this.
1301
1302     This warning is off by default.
1303
1304 .. ghc-flag:: -Wmonomorphism-restriction
1305     :shortdesc: warn when the Monomorphism Restriction is applied
1306     :type: dynamic
1307     :reverse: -Wno-monomorphism-restriction
1308     :category:
1309
1310     .. index::
1311        single: monomorphism restriction, warning
1312
1313     Have the compiler warn/inform you where in your source the Haskell
1314     Monomorphism Restriction is applied. If applied silently the MR can
1315     give rise to unexpected behaviour, so it can be helpful to have an
1316     explicit warning that it is being applied.
1317
1318     This warning is off by default.
1319
1320 .. ghc-flag:: -Wunsupported-llvm-version
1321     :shortdesc: Warn when using :ghc-flag:`-fllvm` with an unsupported
1322         version of LLVM.
1323     :type: dynamic
1324     :reverse: -Wno-monomorphism-restriction
1325     :category:
1326
1327     Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.
1328
1329 .. ghc-flag:: -Wunticked-promoted-constructors
1330     :shortdesc: warn if promoted constructors are not ticked
1331     :type: dynamic
1332     :reverse: -Wno-unticked-promoted-constructors
1333     :category:
1334
1335     .. index::
1336        single: promoted constructor, warning
1337
1338     Warn if a promoted data constructor is used without a tick preceding
1339     its name.
1340
1341     For example: ::
1342
1343         data Nat = Succ Nat | Zero
1344
1345         data Vec n s where
1346           Nil  :: Vec Zero a
1347           Cons :: a -> Vec n a -> Vec (Succ n) a
1348
1349     Will raise two warnings because ``Zero`` and ``Succ`` are not
1350     written as ``'Zero`` and ``'Succ``.
1351
1352     This warning is enabled by default in :ghc-flag:`-Wall` mode.
1353
1354 .. ghc-flag:: -Wunused-binds
1355     :shortdesc: warn about bindings that are unused. Alias for
1356         :ghc-flag:`-Wunused-top-binds`, :ghc-flag:`-Wunused-local-binds` and
1357         :ghc-flag:`-Wunused-pattern-binds`
1358     :type: dynamic
1359     :reverse: -Wno-unused-binds
1360     :category:
1361
1362     .. index::
1363        single: unused binds, warning
1364        single: binds, unused
1365
1366     Report any function definitions (and local bindings) which are
1367     unused. An alias for
1368
1369     -  :ghc-flag:`-Wunused-top-binds`
1370     -  :ghc-flag:`-Wunused-local-binds`
1371     -  :ghc-flag:`-Wunused-pattern-binds`
1372
1373 .. ghc-flag:: -Wunused-top-binds
1374     :shortdesc: warn about top-level bindings that are unused
1375     :type: dynamic
1376     :reverse: -Wno-unused-top-binds
1377     :category:
1378
1379     .. index::
1380        single: unused binds, warning
1381        single: binds, unused
1382
1383     Report any function definitions which are unused.
1384
1385     More precisely, warn if a binding brings into scope a variable that
1386     is not used, except if the variable's name starts with an
1387     underscore. The "starts-with-underscore" condition provides a way to
1388     selectively disable the warning.
1389
1390     A variable is regarded as "used" if
1391
1392     -  It is exported, or
1393
1394     -  It appears in the right hand side of a binding that binds at
1395        least one used variable that is used
1396
1397     For example: ::
1398
1399         module A (f) where
1400         f = let (p,q) = rhs1 in t p  -- No warning: q is unused, but is locally bound
1401         t = rhs3                     -- No warning: f is used, and hence so is t
1402         g = h x                      -- Warning: g unused
1403         h = rhs2                     -- Warning: h is only used in the
1404                                      -- right-hand side of another unused binding
1405         _w = True                    -- No warning: _w starts with an underscore
1406
1407 .. ghc-flag:: -Wunused-local-binds
1408     :shortdesc: warn about local bindings that are unused
1409     :type: dynamic
1410     :reverse: -Wno-unused-local-binds
1411     :category:
1412
1413     .. index::
1414        single: unused binds, warning
1415        single: binds, unused
1416
1417     Report any local definitions which are unused. For example: ::
1418
1419         module A (f) where
1420         f = let (p,q) = rhs1 in t p  -- Warning: q is unused
1421         g = h x                      -- No warning: g is unused, but is a top-level binding
1422
1423 .. ghc-flag:: -Wunused-pattern-binds
1424     :shortdesc: warn about pattern match bindings that are unused
1425     :type: dynamic
1426     :reverse: -Wno-unused-pattern-binds
1427     :category:
1428
1429     .. index::
1430        single: unused binds, warning
1431        single: binds, unused
1432
1433     Warn if a pattern binding binds no variables at all, unless it is a
1434     lone wild-card pattern, or a banged pattern. For example: ::
1435
1436         Just _ = rhs3    -- Warning: unused pattern binding
1437         (_, _) = rhs4    -- Warning: unused pattern binding
1438         _  = rhs3        -- No warning: lone wild-card pattern
1439         !() = rhs4       -- No warning: banged pattern; behaves like seq
1440
1441     In general a lazy pattern binding `p = e` is a no-op if `p` does not
1442     bind any variables.
1443     The motivation for allowing lone wild-card patterns is they are not
1444     very different from ``_v = rhs3``, which elicits no warning; and
1445     they can be useful to add a type constraint, e.g. ``_ = x::Int``. A
1446     banged pattern (see :ref:`bang-patterns`) is *not* a no-op, because
1447     it forces evaluation, and is useful as an alternative to ``seq``.
1448
1449 .. ghc-flag:: -Wunused-imports
1450     :shortdesc: warn about unnecessary imports
1451     :type: dynamic
1452     :reverse: -Wno-unused-imports
1453     :category:
1454
1455     .. index::
1456        single: unused imports, warning
1457        single: imports, unused
1458
1459     Report any modules that are explicitly imported but never used.
1460     However, the form ``import M()`` is never reported as an unused
1461     import, because it is a useful idiom for importing instance
1462     declarations, which are anonymous in Haskell.
1463
1464 .. ghc-flag:: -Wunused-matches
1465     :shortdesc: warn about variables in patterns that aren't used
1466     :type: dynamic
1467     :reverse: -Wno-unused-matches
1468     :category:
1469
1470     .. index::
1471        single: unused matches, warning
1472        single: matches, unused
1473
1474     Report all unused variables which arise from term-level pattern matches,
1475     including patterns consisting of a single variable. For instance
1476     ``f x y = []`` would report ``x`` and ``y`` as unused. The warning
1477     is suppressed if the variable name begins with an underscore, thus: ::
1478
1479         f _x = True
1480
1481     Note that :ghc-flag:`-Wunused-matches` does not warn about variables which
1482     arise from type-level patterns, as found in type family and data family
1483     instances. This must be enabled separately through the
1484     :ghc-flag:`-Wunused-type-patterns` flag.
1485
1486 .. ghc-flag:: -Wunused-do-bind
1487     :shortdesc: warn about do bindings that appear to throw away values of types
1488         other than ``()``
1489     :type: dynamic
1490     :reverse: -Wno-unused-do-bind
1491     :category:
1492
1493     .. index::
1494        single: unused do binding, warning
1495        single: do binding, unused
1496
1497     Report expressions occurring in ``do`` and ``mdo`` blocks that
1498     appear to silently throw information away. For instance
1499     ``do { mapM popInt xs ; return 10 }`` would report the first
1500     statement in the ``do`` block as suspicious, as it has the type
1501     ``StackM [Int]`` and not ``StackM ()``, but that ``[Int]`` value is
1502     not bound to anything. The warning is suppressed by explicitly
1503     mentioning in the source code that your program is throwing
1504     something away: ::
1505
1506         do { _ <- mapM popInt xs ; return 10 }
1507
1508     Of course, in this particular situation you can do even better: ::
1509
1510         do { mapM_ popInt xs ; return 10 }
1511
1512 .. ghc-flag:: -Wunused-type-patterns
1513     :shortdesc: warn about unused type variables which arise from patterns in
1514         in type family and data family instances
1515     :type: dynamic
1516     :reverse: -Wno-unused-type-patterns
1517     :category:
1518
1519     .. index::
1520        single: unused type patterns, warning
1521        single: type patterns, unused
1522
1523     Report all unused implicitly bound type variables which arise from
1524     patterns in type family and data family instances. For instance: ::
1525
1526         type instance F x y = []
1527
1528     would report ``x`` and ``y`` as unused on the right hand side. The warning
1529     is suppressed if the type variable name begins with an underscore, like
1530     so: ::
1531
1532         type instance F _x _y = []
1533
1534     When :extension:`ExplicitForAll` is enabled, explicitly quantified type
1535     variables may also be identified as unused. For instance: ::
1536       
1537         type instance forall x y. F x y = []
1538     
1539     would still report ``x`` and ``y`` as unused on the right hand side
1540
1541     Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-patterns` is
1542     not implied by :ghc-flag:`-Wall`. The rationale for this decision is that
1543     unlike term-level pattern names, type names are often chosen expressly for
1544     documentation purposes, so using underscores in type names can make the
1545     documentation harder to read.
1546     
1547 .. ghc-flag:: -Wunused-foralls
1548     :shortdesc: warn about type variables in user-written
1549         ``forall``\\s that are unused
1550     :type: dynamic
1551     :reverse: -Wno-unused-foralls
1552     :category:
1553
1554     .. index::
1555        single: unused foralls, warning
1556        single: foralls, unused
1557
1558     Report all unused type variables which arise from explicit, user-written
1559     ``forall`` statements. For instance: ::
1560
1561         g :: forall a b c. (b -> b)
1562
1563     would report ``a`` and ``c`` as unused.
1564
1565 .. ghc-flag:: -Wwrong-do-bind
1566     :shortdesc: warn about do bindings that appear to throw away monadic values
1567         that you should have bound instead
1568     :type: dynamic
1569     :reverse: -Wno-wrong-do-bind
1570     :category:
1571
1572     .. index::
1573        single: apparently erroneous do binding, warning
1574        single: do binding, apparently erroneous
1575
1576     Report expressions occurring in ``do`` and ``mdo`` blocks that
1577     appear to lack a binding. For instance
1578     ``do { return (popInt 10) ; return 10 }`` would report the first
1579     statement in the ``do`` block as suspicious, as it has the type
1580     ``StackM (StackM Int)`` (which consists of two nested applications
1581     of the same monad constructor), but which is not then "unpacked" by
1582     binding the result. The warning is suppressed by explicitly
1583     mentioning in the source code that your program is throwing
1584     something away: ::
1585
1586         do { _ <- return (popInt 10) ; return 10 }
1587
1588     For almost all sensible programs this will indicate a bug, and you
1589     probably intended to write: ::
1590
1591         do { popInt 10 ; return 10 }
1592
1593 .. ghc-flag:: -Winline-rule-shadowing
1594     :shortdesc: Warn if a rewrite RULE might fail to fire because the
1595         function might be inlined before the rule has a chance to fire.
1596         See :ref:`rules-inline`.
1597     :type: dynamic
1598     :reverse: -Wno-inline-rule-shadowing
1599     :category:
1600
1601     Warn if a rewrite RULE might fail to fire because the function might
1602     be inlined before the rule has a chance to fire. See
1603     :ref:`rules-inline`.
1604
1605 .. ghc-flag:: -Wcpp-undef
1606     :shortdesc: warn on uses of the `#if` directive on undefined identifiers
1607     :type: dynamic
1608     :category:
1609
1610     :since: 8.2
1611
1612     This flag passes ``-Wundef`` to the C pre-processor (if its being used)
1613     which causes the pre-processor to warn on uses of the `#if` directive on
1614     undefined identifiers.
1615
1616 .. ghc-flag:: -Wunbanged-strict-patterns
1617     :shortdesc: warn on pattern bind of unlifted variable that is neither bare
1618         nor banged
1619     :type: dynamic
1620     :reverse: -Wno-unbanged-strict-patterns
1621     :category:
1622
1623     This flag warns whenever you write a pattern that binds a variable whose
1624     type is unlifted, and yet the pattern is not a bang pattern nor a bare variable.
1625     See :ref:`glasgow-unboxed` for information about unlifted types.
1626
1627 .. ghc-flag:: -Wmissing-home-modules
1628     :shortdesc: warn when encountering a home module imported, but not listed
1629         on the command line. Useful for cabal to ensure GHC won't pick
1630         up modules, not listed neither in ``exposed-modules``, nor in
1631         ``other-modules``.
1632     :type: dynamic
1633     :reverse: -Wno-missing-home-modules
1634     :category:
1635
1636     :since: 8.2
1637
1638     When a module provided by the package currently being compiled
1639     (i.e. the "home" package) is imported, but not explicitly listed in
1640     command line as a target. Useful for Cabal to ensure GHC won't
1641     pick up modules, not listed neither in ``exposed-modules``, nor in
1642     ``other-modules``.
1643
1644 .. ghc-flag:: -Wpartial-fields
1645     :shortdesc: warn when defining a partial record field.
1646     :type: dynamic
1647     :reverse: -Wno-partial-fields
1648     :category:
1649
1650     :since: 8.4
1651
1652     The option :ghc-flag:`-Wpartial-fields` warns about record fields that could
1653     fail when accessed via a lacking constructor. The function ``f`` below will
1654     fail when applied to ``Bar``, so the compiler will emit a warning at its
1655     definition when :ghc-flag:`-Wpartial-fields` is enabled.
1656
1657     The warning is suppressed if the field name begins with an underscore. ::
1658
1659         data Foo = Foo { f :: Int } | Bar
1660
1661 If you're feeling really paranoid, the :ghc-flag:`-dcore-lint` option is a good choice.
1662 It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
1663 sanity, not yours.)