users-guide: Fix typo
[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:`-Wmissed-extra-shared-lib`
43     * :ghc-flag:`-Wtabs`
44     * :ghc-flag:`-Wunrecognised-warning-flags`
45     * :ghc-flag:`-Winaccessible-code`
46     * :ghc-flag:`-Wstar-is-type`
47     * :ghc-flag:`-Wstar-binder`
48     * :ghc-flag:`-Wspace-after-bang`
49
50 The following flags are simple ways to select standard "packages" of warnings:
51
52 .. ghc-flag:: -W
53     :shortdesc: enable normal warnings
54     :type: dynamic
55     :reverse: -w
56     :category:
57
58     Provides the standard warnings plus
59
60     .. hlist::
61         :columns: 3
62
63         * :ghc-flag:`-Wunused-binds`
64         * :ghc-flag:`-Wunused-matches`
65         * :ghc-flag:`-Wunused-foralls`
66         * :ghc-flag:`-Wunused-imports`
67         * :ghc-flag:`-Wincomplete-patterns`
68         * :ghc-flag:`-Wdodgy-exports`
69         * :ghc-flag:`-Wdodgy-imports`
70         * :ghc-flag:`-Wunbanged-strict-patterns`
71
72 .. ghc-flag:: -Wall
73     :shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
74     :type: dynamic
75     :reverse: -w
76     :category:
77
78     Turns on all warning options that indicate potentially suspicious
79     code. The warnings that are *not* enabled by :ghc-flag:`-Wall` are
80
81     .. hlist::
82         :columns: 3
83
84         * :ghc-flag:`-Wincomplete-uni-patterns`
85         * :ghc-flag:`-Wincomplete-record-updates`
86         * :ghc-flag:`-Wmonomorphism-restriction`
87         * :ghc-flag:`-Wimplicit-prelude`
88         * :ghc-flag:`-Wmissing-local-signatures`
89         * :ghc-flag:`-Wmissing-exported-signatures`
90         * :ghc-flag:`-Wmissing-export-lists`
91         * :ghc-flag:`-Wmissing-import-lists`
92         * :ghc-flag:`-Wmissing-home-modules`
93         * :ghc-flag:`-Widentities`
94         * :ghc-flag:`-Wredundant-constraints`
95         * :ghc-flag:`-Wpartial-fields`
96         * :ghc-flag:`-Wmissed-specialisations`
97         * :ghc-flag:`-Wall-missed-specialisations`
98
99 .. ghc-flag:: -Weverything
100     :shortdesc: enable all warnings supported by GHC
101     :type: dynamic
102     :category:
103
104     Turns on every single warning supported by the compiler.
105
106 .. ghc-flag:: -Wcompat
107     :shortdesc: enable future compatibility warnings
108         (details in :ref:`options-sanity`)
109     :type: dynamic
110     :reverse: -Wno-compat
111     :category:
112
113     Turns on warnings that will be enabled by default in the future, but remain
114     off in normal compilations for the time being. This allows library authors
115     eager to make their code future compatible to adapt to new features before
116     they even generate warnings.
117
118     This currently enables
119
120     .. hlist::
121         :columns: 3
122
123         * :ghc-flag:`-Wmissing-monadfail-instances`
124         * :ghc-flag:`-Wsemigroup`
125         * :ghc-flag:`-Wnoncanonical-monoid-instances`
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:: -Wincomplete-patterns
779     :shortdesc: warn when a pattern match could fail
780     :type: dynamic
781     :reverse: -Wno-incomplete-patterns
782     :category:
783
784     .. index::
785        single: incomplete patterns, warning
786        single: patterns, incomplete
787
788     The option :ghc-flag:`-Wincomplete-patterns` warns about places where a
789     pattern-match might fail at runtime. The function ``g`` below will
790     fail when applied to non-empty lists, so the compiler will emit a
791     warning about this when :ghc-flag:`-Wincomplete-patterns` is enabled. ::
792
793         g [] = 2
794
795     This option isn't enabled by default because it can be a bit noisy,
796     and it doesn't always indicate a bug in the program. However, it's
797     generally considered good practice to cover all the cases in your
798     functions, and it is switched on by :ghc-flag:`-W`.
799
800
801 .. ghc-flag:: -Wincomplete-uni-patterns
802     :shortdesc: warn when a pattern match in a lambda expression or
803         pattern binding could fail
804     :type: dynamic
805     :reverse: -Wno-incomplete-uni-patterns
806     :category:
807
808     The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar to
809     :ghc-flag:`-Wincomplete-patterns`, except that it applies only to
810     lambda-expressions and pattern bindings, constructs that only allow a
811     single pattern: ::
812
813         h = \[] -> 2
814         Just k = f y
815
816 .. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩
817     :shortdesc: the iteration limit for the pattern match checker
818     :type: dynamic
819     :category:
820
821     :default: 2000000
822
823     Sets how many iterations of the pattern-match checker will perform before
824     giving up. This limit is to catch cases where pattern-match checking might
825     be excessively costly (due to the exponential complexity of coverage
826     checking in the general case). It typically shouldn't be necessary to set
827     this unless GHC informs you that it has exceeded the pattern match checker's
828     iteration limit (in which case you may want to consider refactoring your
829     pattern match, for the sake of future readers of your code.
830
831 .. ghc-flag:: -Wincomplete-record-updates
832     :shortdesc: warn when a record update could fail
833     :type: dynamic
834     :reverse: -Wno-incomplete-record-updates
835     :category:
836
837     .. index::
838        single: incomplete record updates, warning
839        single: record updates, incomplete
840
841     The function ``f`` below will fail when applied to ``Bar``, so the
842     compiler will emit a warning about this when
843     :ghc-flag:`-Wincomplete-record-updates` is enabled. ::
844
845         data Foo = Foo { x :: Int }
846                  | Bar
847
848         f :: Foo -> Foo
849         f foo = foo { x = 6 }
850
851     This option isn't enabled by default because it can be very noisy,
852     and it often doesn't indicate a bug in the program.
853
854 .. ghc-flag:: -Wmissing-deriving-strategies
855     :shortdesc: warn when a deriving clause is missing a deriving strategy
856     :type: dynamic
857     :reverse: -Wno-missing-deriving-strategies
858     :category:
859
860     :since: 8.8.1
861
862     The datatype below derives the ``Eq`` typeclass, but doesn't specify a
863     strategy. When :ghc-flag:`-Wmissing-deriving-strategies` is enabled,
864     the compiler will emit a warning about this. ::
865
866         data Foo a = Foo a
867           deriving (Eq)
868
869     The compiler will warn here that the deriving clause doesn't specify a
870     strategy. If the warning is enabled, but :extension:`DerivingStrategies` is
871     not enabled, the compiler will suggest turning on the
872     :extension:`DerivingStrategies` extension. This option is not on by default,
873     having to be turned on manually or with :ghc-flag:`-Weverything`.
874
875 .. ghc-flag:: -Wmissing-fields
876     :shortdesc: warn when fields of a record are uninitialised
877     :type: dynamic
878     :reverse: -Wno-missing-fields
879     :category:
880
881     .. index::
882        single: missing fields, warning
883        single: fields, missing
884
885     This option is on by default, and warns you whenever the
886     construction of a labelled field constructor isn't complete, missing
887     initialisers for one or more fields. While not an error (the missing
888     fields are initialised with bottoms), it is often an indication of a
889     programmer error.
890
891 .. ghc-flag:: -Wmissing-export-lists
892     :shortdesc: warn when a module declaration does not explicitly list all
893         exports
894     :type: dynamic
895     :reverse: -fnowarn-missing-export-lists
896     :category:
897
898     :since: 8.4.1
899
900     .. index::
901        single: missing export lists, warning
902        single: export lists, missing
903
904     This flag warns if you declare a module without declaring an explicit
905     export list. For example ::
906
907         module M where
908
909           p x = x
910
911     The :ghc-flag:`-Wmissing-export-lists` flag will warn that ``M`` does not
912     declare an export list. Declaring an explicit export list for ``M`` enables
913     GHC dead code analysis, prevents accidental export of names and can ease
914     optimizations like inlining.
915
916 .. ghc-flag:: -Wmissing-import-lists
917     :shortdesc: warn when an import declaration does not explicitly list all the
918         names brought into scope
919     :type: dynamic
920     :reverse: -fnowarn-missing-import-lists
921     :category:
922
923     .. index::
924        single: missing import lists, warning
925        single: import lists, missing
926
927     This flag warns if you use an unqualified ``import`` declaration
928     that does not explicitly list the entities brought into scope. For
929     example ::
930
931         module M where
932           import X( f )
933           import Y
934           import qualified Z
935           p x = f x x
936
937     The :ghc-flag:`-Wmissing-import-lists` flag will warn about the import of
938     ``Y`` but not ``X`` If module ``Y`` is later changed to export (say) ``f``,
939     then the reference to ``f`` in ``M`` will become ambiguous. No warning is
940     produced for the import of ``Z`` because extending ``Z``\'s exports would be
941     unlikely to produce ambiguity in ``M``.
942
943 .. ghc-flag:: -Wmissing-methods
944     :shortdesc: warn when class methods are undefined
945     :type: dynamic
946     :reverse: -Wno-missing-methods
947     :category:
948
949     .. index::
950        single: missing methods, warning
951        single: methods, missing
952
953     This option is on by default, and warns you whenever an instance
954     declaration is missing one or more methods, and the corresponding
955     class declaration has no default declaration for them.
956
957     The ``MINIMAL`` pragma can be used to change which combination of
958     methods will be required for instances of a particular class. See
959     :ref:`minimal-pragma`.
960
961 .. ghc-flag:: -Wmissing-signatures
962     :shortdesc: warn about top-level functions without signatures
963     :type: dynamic
964     :reverse: -Wno-missing-signatures
965     :category:
966
967     .. index::
968        single: type signatures, missing
969
970     If you would like GHC to check that every top-level function/value
971     has a type signature, use the :ghc-flag:`-Wmissing-signatures` option.
972     As part of the warning GHC also reports the inferred type. The
973     option is off by default.
974
975 .. ghc-flag:: -Wmissing-exported-sigs
976     :shortdesc: *(deprecated)*
977         warn about top-level functions without signatures, only if they
978         are exported. takes precedence over -Wmissing-signatures
979     :type: dynamic
980     :reverse: -Wno-missing-exported-sigs
981     :category:
982
983     .. index::
984        single: type signatures, missing
985
986     This option is now deprecated in favour of
987     :ghc-flag:`-Wmissing-exported-signatures`.
988
989 .. ghc-flag:: -Wmissing-exported-signatures
990     :shortdesc: warn about top-level functions without signatures, only if they
991         are exported. takes precedence over -Wmissing-signatures
992     :type: dynamic
993     :reverse: -Wno-missing-exported-signatures
994     :category:
995
996     .. index::
997        single: type signatures, missing
998
999     If you would like GHC to check that every exported top-level
1000     function/value has a type signature, but not check unexported
1001     values, use the :ghc-flag:`-Wmissing-exported-signatures`
1002     option. This option takes precedence over
1003     :ghc-flag:`-Wmissing-signatures`. As part of the warning GHC also
1004     reports the inferred type. The option is off by default.
1005
1006 .. ghc-flag:: -Wmissing-local-sigs
1007     :shortdesc: *(deprecated)*
1008         warn about polymorphic local bindings without signatures
1009     :type: dynamic
1010     :reverse: -Wno-missing-local-sigs
1011     :category:
1012
1013     .. index::
1014        single: type signatures, missing
1015
1016     This option is now deprecated in favour of
1017     :ghc-flag:`-Wmissing-local-signatures`.
1018
1019 .. ghc-flag:: -Wmissing-local-signatures
1020     :shortdesc: warn about polymorphic local bindings without signatures
1021     :type: dynamic
1022     :reverse: -Wno-missing-local-signatures
1023     :category:
1024
1025     .. index::
1026        single: type signatures, missing
1027
1028     If you use the :ghc-flag:`-Wmissing-local-signatures` flag GHC
1029     will warn you about any polymorphic local bindings. As part of the
1030     warning GHC also reports the inferred type. The option is off by
1031     default.
1032
1033 .. ghc-flag:: -Wmissing-pattern-synonym-signatures
1034     :shortdesc: warn when pattern synonyms do not have type signatures
1035     :type: dynamic
1036     :reverse: -Wno-missing-pattern-synonym-signatures
1037     :category:
1038
1039     .. index::
1040          single: type signatures, missing, pattern synonyms
1041
1042     If you would like GHC to check that every pattern synonym has a
1043     type signature, use the
1044     :ghc-flag:`-Wmissing-pattern-synonym-signatures` option. If this
1045     option is used in conjunction with
1046     :ghc-flag:`-Wmissing-exported-signatures` then only exported pattern
1047     synonyms must have a type signature. GHC also reports the inferred
1048     type. This option is off by default.
1049
1050 .. ghc-flag:: -Wname-shadowing
1051     :shortdesc: warn when names are shadowed
1052     :type: dynamic
1053     :reverse: -Wno-name-shadowing
1054     :category:
1055
1056     .. index::
1057        single: shadowing, warning
1058
1059     This option causes a warning to be emitted whenever an inner-scope
1060     value has the same name as an outer-scope value, i.e. the inner
1061     value shadows the outer one. This can catch typographical errors
1062     that turn into hard-to-find bugs, e.g., in the inadvertent capture
1063     of what would be a recursive call in
1064     ``f = ... let f = id in ... f ...``.
1065
1066     The warning is suppressed for names beginning with an underscore.
1067     For example ::
1068
1069         f x = do { _ignore <- this; _ignore <- that; return (the other) }
1070
1071 .. ghc-flag:: -Worphans
1072     :shortdesc: warn when the module contains :ref:`orphan instance declarations
1073         or rewrite rules <orphan-modules>`
1074     :type: dynamic
1075     :reverse: -Wno-orphans
1076     :category:
1077
1078     .. index::
1079        single: orphan instances, warning
1080        single: orphan rules, warning
1081
1082     These flags cause a warning to be emitted whenever the module
1083     contains an "orphan" instance declaration or rewrite rule. An
1084     instance declaration is an orphan if it appears in a module in which
1085     neither the class nor the type being instanced are declared in the
1086     same module. A rule is an orphan if it is a rule for a function
1087     declared in another module. A module containing any orphans is
1088     called an orphan module.
1089
1090     The trouble with orphans is that GHC must pro-actively read the
1091     interface files for all orphan modules, just in case their instances
1092     or rules play a role, whether or not the module's interface would
1093     otherwise be of any use. See :ref:`orphan-modules` for details.
1094
1095     The flag :ghc-flag:`-Worphans` warns about user-written orphan rules or
1096     instances.
1097
1098 .. ghc-flag:: -Woverlapping-patterns
1099     :shortdesc: warn about overlapping patterns
1100     :type: dynamic
1101     :reverse: -Wno-overlapping-patterns
1102     :category:
1103
1104     .. index::
1105        single: overlapping patterns, warning
1106        single: patterns, overlapping
1107
1108     By default, the compiler will warn you if a set of patterns are
1109     overlapping, e.g., ::
1110
1111         f :: String -> Int
1112         f []     = 0
1113         f (_:xs) = 1
1114         f "2"    = 2
1115
1116     where the last pattern match in ``f`` won't ever be reached, as the
1117     second pattern overlaps it. More often than not, redundant patterns
1118     is a programmer mistake/error, so this option is enabled by default.
1119
1120 .. ghc-flag:: -Winaccessible-code
1121     :shortdesc: warn about inaccessible code
1122     :type: dynamic
1123     :reverse: -Wno-inaccessible-code
1124     :category:
1125
1126     .. index::
1127        single: inaccessible code, warning
1128        single: inaccessible
1129
1130     By default, the compiler will warn you if types make a branch inaccessible.
1131     This generally requires GADTs or similar extensions.
1132
1133     Take, for example, the following program ::
1134
1135         {-# LANGUAGE GADTs #-}
1136
1137         data Foo a where
1138          Foo1 :: Foo Char
1139          Foo2 :: Foo Int
1140
1141         data TyEquality a b where
1142                 Refl :: TyEquality a a
1143
1144         checkTEQ :: Foo t -> Foo u -> Maybe (TyEquality t u)
1145         checkTEQ x y = error "unimportant"
1146
1147         step2 :: Bool
1148         step2 = case checkTEQ Foo1 Foo2 of
1149                  Just Refl -> True -- Inaccessible code
1150                  Nothing -> False
1151
1152     The ``Just Refl`` case in ``step2`` is inaccessible, because in order for
1153     ``checkTEQ`` to be able to produce a ``Just``, ``t ~ u`` must hold, but
1154     since we're passing ``Foo1`` and ``Foo2`` here, it follows that ``t ~
1155     Char``, and ``u ~ Int``, and thus ``t ~ u`` cannot hold.
1156
1157 .. ghc-flag:: -Wstar-is-type
1158      :shortdesc: warn when ``*`` is used to mean ``Data.Kind.Type``
1159      :type: dynamic
1160      :reverse: -Wno-star-is-type
1161      :category:
1162
1163      :since: 8.6
1164
1165      The use of ``*`` to denote the kind of inhabited types relies on the
1166      :extension:`StarIsType` extension, which in a future release will be
1167      turned off by default and then possibly removed. The reasons for this and
1168      the deprecation schedule are described in `GHC proposal #30
1169      <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst>`__.
1170
1171      This warning allows to detect such uses of ``*`` before the actual
1172      breaking change takes place. The recommended fix is to replace ``*`` with
1173      ``Type`` imported from ``Data.Kind``.
1174
1175      Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
1176      default, but will be switched on in a future GHC release.
1177
1178 .. ghc-flag:: -Wstar-binder
1179      :shortdesc: warn about binding the ``(*)`` type operator despite
1180          :ghc-flag:`-XStarIsType`
1181      :type: dynamic
1182      :reverse: -Wno-star-binder
1183
1184      Under :ghc-flag:`-XStarIsType`, a ``*`` in types is not an operator nor
1185      even a name, it is special syntax that stands for ``Data.Kind.Type``. This
1186      means that an expression like ``Either * Char`` is parsed as ``Either (*)
1187      Char`` and not ``(*) Either Char``.
1188
1189      In binding positions, we have similar parsing rules. Consider the following
1190      example ::
1191
1192          {-# LANGUAGE TypeOperators, TypeFamilies, StarIsType #-}
1193
1194          type family a + b
1195          type family a * b
1196
1197      While ``a + b`` is parsed as ``(+) a b`` and becomes a binding position for
1198      the ``(+)`` type operator, ``a * b`` is parsed as ``a (*) b`` and is rejected.
1199
1200      As a workaround, we allow to bind ``(*)`` in prefix form::
1201
1202          type family (*) a b
1203
1204      This is a rather fragile arrangement, as generally a programmer expects
1205      ``(*) a b`` to be equivalent to ``a * b``. With :ghc-flag:`-Wstar-binder`
1206      we warn when this special treatment of ``(*)`` takes place.
1207
1208 .. ghc-flag:: -Wsimplifiable-class-constraints
1209     :shortdesc: Warn about class constraints in a type signature that can
1210         be simplified using a top-level instance declaration.
1211     :type: dynamic
1212     :reverse: -Wno-simplifiable-class-constraints
1213     :category:
1214
1215     :since: 8.2
1216
1217     .. index::
1218        single: simplifiable class constraints, warning
1219
1220     Warn about class constraints in a type signature that can be simplified
1221     using a top-level instance declaration.  For example: ::
1222
1223        f :: Eq [a] => a -> a
1224
1225     Here the ``Eq [a]`` in the signature overlaps with the top-level
1226     instance for ``Eq [a]``.  GHC goes to some efforts to use the former,
1227     but if it should use the latter, it would then have an
1228     insoluble ``Eq a`` constraint.  Best avoided by instead writing: ::
1229
1230        f :: Eq a => a -> a
1231
1232     This option is on by default. As usual you can suppress it on a
1233     per-module basis with :ghc-flag:`-Wno-simplifiable-class-constraints
1234     <-Wsimplifiable-class-constraints>`.
1235
1236 .. ghc-flag:: -Wspace-after-bang
1237      :shortdesc: warn for missing space before the second argument
1238         of an infix definition of ``(!)`` when
1239         :ghc-flag:`-XBangPatterns` are not enabled
1240      :type: dynamic
1241      :reverse: -Wno-missing-space-after-bang
1242 .. ghc-flag:: -Wtabs
1243     :shortdesc: warn if there are tabs in the source file
1244     :type: dynamic
1245     :reverse: -Wno-tabs
1246     :category:
1247
1248     .. index::
1249        single: tabs, warning
1250
1251     Have the compiler warn if there are tabs in your source file.
1252
1253 .. ghc-flag:: -Wtype-defaults
1254     :shortdesc: warn when defaulting happens
1255     :type: dynamic
1256     :reverse: -Wno-type-defaults
1257     :category:
1258
1259     .. index::
1260        single: defaulting mechanism, warning
1261
1262     Have the compiler warn/inform you where in your source the Haskell
1263     defaulting mechanism for numeric types kicks in. This is useful
1264     information when converting code from a context that assumed one
1265     default into one with another, e.g., the ‘default default’ for
1266     Haskell 1.4 caused the otherwise unconstrained value ``1`` to be
1267     given the type ``Int``, whereas Haskell 98 and later defaults it to
1268     ``Integer``. This may lead to differences in performance and
1269     behaviour, hence the usefulness of being non-silent about this.
1270
1271     This warning is off by default.
1272
1273 .. ghc-flag:: -Wmonomorphism-restriction
1274     :shortdesc: warn when the Monomorphism Restriction is applied
1275     :type: dynamic
1276     :reverse: -Wno-monomorphism-restriction
1277     :category:
1278
1279     .. index::
1280        single: monomorphism restriction, warning
1281
1282     Have the compiler warn/inform you where in your source the Haskell
1283     Monomorphism Restriction is applied. If applied silently the MR can
1284     give rise to unexpected behaviour, so it can be helpful to have an
1285     explicit warning that it is being applied.
1286
1287     This warning is off by default.
1288
1289 .. ghc-flag:: -Wunsupported-llvm-version
1290     :shortdesc: Warn when using :ghc-flag:`-fllvm` with an unsupported
1291         version of LLVM.
1292     :type: dynamic
1293     :reverse: -Wno-monomorphism-restriction
1294     :category:
1295
1296     Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.
1297
1298 .. ghc-flag:: -Wmissed-extra-shared-lib
1299     :shortdesc: Warn when GHCi can't load a shared lib.
1300     :type: dynamic
1301     :reverse: -Wno-missed-extra-shared-lib
1302     :category:
1303
1304     Warn when GHCi can't load a shared lib it deduced it should load
1305     when loading a package and analyzing the extra-libraries stanza
1306     of the target package description.
1307
1308 .. ghc-flag:: -Wunticked-promoted-constructors
1309     :shortdesc: warn if promoted constructors are not ticked
1310     :type: dynamic
1311     :reverse: -Wno-unticked-promoted-constructors
1312     :category:
1313
1314     .. index::
1315        single: promoted constructor, warning
1316
1317     Warn if a promoted data constructor is used without a tick preceding
1318     its name.
1319
1320     For example: ::
1321
1322         data Nat = Succ Nat | Zero
1323
1324         data Vec n s where
1325           Nil  :: Vec Zero a
1326           Cons :: a -> Vec n a -> Vec (Succ n) a
1327
1328     Will raise two warnings because ``Zero`` and ``Succ`` are not
1329     written as ``'Zero`` and ``'Succ``.
1330
1331     This warning is enabled by default in :ghc-flag:`-Wall` mode.
1332
1333 .. ghc-flag:: -Wunused-binds
1334     :shortdesc: warn about bindings that are unused. Alias for
1335         :ghc-flag:`-Wunused-top-binds`, :ghc-flag:`-Wunused-local-binds` and
1336         :ghc-flag:`-Wunused-pattern-binds`
1337     :type: dynamic
1338     :reverse: -Wno-unused-binds
1339     :category:
1340
1341     .. index::
1342        single: unused binds, warning
1343        single: binds, unused
1344
1345     Report any function definitions (and local bindings) which are
1346     unused. An alias for
1347
1348     -  :ghc-flag:`-Wunused-top-binds`
1349     -  :ghc-flag:`-Wunused-local-binds`
1350     -  :ghc-flag:`-Wunused-pattern-binds`
1351
1352 .. ghc-flag:: -Wunused-top-binds
1353     :shortdesc: warn about top-level bindings that are unused
1354     :type: dynamic
1355     :reverse: -Wno-unused-top-binds
1356     :category:
1357
1358     .. index::
1359        single: unused binds, warning
1360        single: binds, unused
1361
1362     Report any function definitions which are unused.
1363
1364     More precisely, warn if a binding brings into scope a variable that
1365     is not used, except if the variable's name starts with an
1366     underscore. The "starts-with-underscore" condition provides a way to
1367     selectively disable the warning.
1368
1369     A variable is regarded as "used" if
1370
1371     -  It is exported, or
1372
1373     -  It appears in the right hand side of a binding that binds at
1374        least one used variable that is used
1375
1376     For example: ::
1377
1378         module A (f) where
1379         f = let (p,q) = rhs1 in t p  -- No warning: q is unused, but is locally bound
1380         t = rhs3                     -- No warning: f is used, and hence so is t
1381         g = h x                      -- Warning: g unused
1382         h = rhs2                     -- Warning: h is only used in the
1383                                      -- right-hand side of another unused binding
1384         _w = True                    -- No warning: _w starts with an underscore
1385
1386 .. ghc-flag:: -Wunused-local-binds
1387     :shortdesc: warn about local bindings that are unused
1388     :type: dynamic
1389     :reverse: -Wno-unused-local-binds
1390     :category:
1391
1392     .. index::
1393        single: unused binds, warning
1394        single: binds, unused
1395
1396     Report any local definitions which are unused. For example: ::
1397
1398         module A (f) where
1399         f = let (p,q) = rhs1 in t p  -- Warning: q is unused
1400         g = h x                      -- No warning: g is unused, but is a top-level binding
1401
1402 .. ghc-flag:: -Wunused-pattern-binds
1403     :shortdesc: warn about pattern match bindings that are unused
1404     :type: dynamic
1405     :reverse: -Wno-unused-pattern-binds
1406     :category:
1407
1408     .. index::
1409        single: unused binds, warning
1410        single: binds, unused
1411
1412     Warn if a pattern binding binds no variables at all, unless it is a
1413     lone wild-card pattern, or a banged pattern. For example: ::
1414
1415         Just _ = rhs3    -- Warning: unused pattern binding
1416         (_, _) = rhs4    -- Warning: unused pattern binding
1417         _  = rhs3        -- No warning: lone wild-card pattern
1418         !() = rhs4       -- No warning: banged pattern; behaves like seq
1419
1420     In general a lazy pattern binding `p = e` is a no-op if `p` does not
1421     bind any variables.
1422     The motivation for allowing lone wild-card patterns is they are not
1423     very different from ``_v = rhs3``, which elicits no warning; and
1424     they can be useful to add a type constraint, e.g. ``_ = x::Int``. A
1425     banged pattern (see :ref:`bang-patterns`) is *not* a no-op, because
1426     it forces evaluation, and is useful as an alternative to ``seq``.
1427
1428 .. ghc-flag:: -Wunused-imports
1429     :shortdesc: warn about unnecessary imports
1430     :type: dynamic
1431     :reverse: -Wno-unused-imports
1432     :category:
1433
1434     .. index::
1435        single: unused imports, warning
1436        single: imports, unused
1437
1438     Report any modules that are explicitly imported but never used.
1439     However, the form ``import M()`` is never reported as an unused
1440     import, because it is a useful idiom for importing instance
1441     declarations, which are anonymous in Haskell.
1442
1443 .. ghc-flag:: -Wunused-matches
1444     :shortdesc: warn about variables in patterns that aren't used
1445     :type: dynamic
1446     :reverse: -Wno-unused-matches
1447     :category:
1448
1449     .. index::
1450        single: unused matches, warning
1451        single: matches, unused
1452
1453     Report all unused variables which arise from term-level pattern matches,
1454     including patterns consisting of a single variable. For instance
1455     ``f x y = []`` would report ``x`` and ``y`` as unused. The warning
1456     is suppressed if the variable name begins with an underscore, thus: ::
1457
1458         f _x = True
1459
1460     Note that :ghc-flag:`-Wunused-matches` does not warn about variables which
1461     arise from type-level patterns, as found in type family and data family
1462     instances. This must be enabled separately through the
1463     :ghc-flag:`-Wunused-type-patterns` flag.
1464
1465 .. ghc-flag:: -Wunused-do-bind
1466     :shortdesc: warn about do bindings that appear to throw away values of types
1467         other than ``()``
1468     :type: dynamic
1469     :reverse: -Wno-unused-do-bind
1470     :category:
1471
1472     .. index::
1473        single: unused do binding, warning
1474        single: do binding, unused
1475
1476     Report expressions occurring in ``do`` and ``mdo`` blocks that
1477     appear to silently throw information away. For instance
1478     ``do { mapM popInt xs ; return 10 }`` would report the first
1479     statement in the ``do`` block as suspicious, as it has the type
1480     ``StackM [Int]`` and not ``StackM ()``, but that ``[Int]`` value is
1481     not bound to anything. The warning is suppressed by explicitly
1482     mentioning in the source code that your program is throwing
1483     something away: ::
1484
1485         do { _ <- mapM popInt xs ; return 10 }
1486
1487     Of course, in this particular situation you can do even better: ::
1488
1489         do { mapM_ popInt xs ; return 10 }
1490
1491 .. ghc-flag:: -Wunused-type-patterns
1492     :shortdesc: warn about unused type variables which arise from patterns in
1493         in type family and data family instances
1494     :type: dynamic
1495     :reverse: -Wno-unused-type-patterns
1496     :category:
1497
1498     .. index::
1499        single: unused type patterns, warning
1500        single: type patterns, unused
1501
1502     Report all unused implicitly bound type variables which arise from
1503     patterns in type family and data family instances. For instance: ::
1504
1505         type instance F x y = []
1506
1507     would report ``x`` and ``y`` as unused on the right hand side. The warning
1508     is suppressed if the type variable name begins with an underscore, like
1509     so: ::
1510
1511         type instance F _x _y = []
1512
1513     When :extension:`ExplicitForAll` is enabled, explicitly quantified type
1514     variables may also be identified as unused. For instance: ::
1515
1516         type instance forall x y. F x y = []
1517
1518     would still report ``x`` and ``y`` as unused on the right hand side
1519
1520     Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-patterns` is
1521     not implied by :ghc-flag:`-Wall`. The rationale for this decision is that
1522     unlike term-level pattern names, type names are often chosen expressly for
1523     documentation purposes, so using underscores in type names can make the
1524     documentation harder to read.
1525
1526 .. ghc-flag:: -Wunused-foralls
1527     :shortdesc: warn about type variables in user-written
1528         ``forall``\\s that are unused
1529     :type: dynamic
1530     :reverse: -Wno-unused-foralls
1531     :category:
1532
1533     .. index::
1534        single: unused foralls, warning
1535        single: foralls, unused
1536
1537     Report all unused type variables which arise from explicit, user-written
1538     ``forall`` statements. For instance: ::
1539
1540         g :: forall a b c. (b -> b)
1541
1542     would report ``a`` and ``c`` as unused.
1543
1544 .. ghc-flag:: -Wunused-record-wildcards
1545     :shortdesc: Warn about record wildcard matches when none of the bound variables
1546       are used.
1547     :type: dynamic
1548     :since: 8.10.1
1549     :reverse: -Wno-unused-record-wildcards
1550     :category:
1551
1552     .. index::
1553        single: unused, warning, record wildcards
1554
1555     Report all record wildcards where none of the variables bound implicitly
1556     are used. For instance: ::
1557
1558
1559         data P = P { x :: Int, y :: Int }
1560
1561         f1 :: P -> Int
1562         f1 P{..} = 1 + 3
1563
1564     would report that the ``P{..}`` match is unused.
1565
1566 .. ghc-flag:: -Wredundant-record-wildcards
1567     :shortdesc: Warn about record wildcard matches when the wildcard binds no patterns.
1568     :type: dynamic
1569     :since: 8.10.1
1570     :reverse: -Wno-redundant-record-wildcards
1571     :category:
1572
1573     .. index::
1574        single: unused, warning, record wildcards
1575
1576     Report all record wildcards where the wild card match binds no patterns.
1577     For instance: ::
1578
1579
1580         data P = P { x :: Int, y :: Int }
1581
1582         f1 :: P -> Int
1583         f1 P{x,y,..} = x + y
1584
1585     would report that the ``P{x, y, ..}`` match has a redundant use of ``..``.
1586
1587
1588 .. ghc-flag:: -Wwrong-do-bind
1589     :shortdesc: warn about do bindings that appear to throw away monadic values
1590         that you should have bound instead
1591     :type: dynamic
1592     :reverse: -Wno-wrong-do-bind
1593     :category:
1594
1595     .. index::
1596        single: apparently erroneous do binding, warning
1597        single: do binding, apparently erroneous
1598
1599     Report expressions occurring in ``do`` and ``mdo`` blocks that
1600     appear to lack a binding. For instance
1601     ``do { return (popInt 10) ; return 10 }`` would report the first
1602     statement in the ``do`` block as suspicious, as it has the type
1603     ``StackM (StackM Int)`` (which consists of two nested applications
1604     of the same monad constructor), but which is not then "unpacked" by
1605     binding the result. The warning is suppressed by explicitly
1606     mentioning in the source code that your program is throwing
1607     something away: ::
1608
1609         do { _ <- return (popInt 10) ; return 10 }
1610
1611     For almost all sensible programs this will indicate a bug, and you
1612     probably intended to write: ::
1613
1614         do { popInt 10 ; return 10 }
1615
1616 .. ghc-flag:: -Winline-rule-shadowing
1617     :shortdesc: Warn if a rewrite RULE might fail to fire because the
1618         function might be inlined before the rule has a chance to fire.
1619         See :ref:`rules-inline`.
1620     :type: dynamic
1621     :reverse: -Wno-inline-rule-shadowing
1622     :category:
1623
1624     Warn if a rewrite RULE might fail to fire because the function might
1625     be inlined before the rule has a chance to fire. See
1626     :ref:`rules-inline`.
1627
1628 .. ghc-flag:: -Wcpp-undef
1629     :shortdesc: warn on uses of the `#if` directive on undefined identifiers
1630     :type: dynamic
1631     :category:
1632
1633     :since: 8.2
1634
1635     This flag passes ``-Wundef`` to the C pre-processor (if its being used)
1636     which causes the pre-processor to warn on uses of the `#if` directive on
1637     undefined identifiers.
1638
1639 .. ghc-flag:: -Wunbanged-strict-patterns
1640     :shortdesc: warn on pattern bind of unlifted variable that is neither bare
1641         nor banged
1642     :type: dynamic
1643     :reverse: -Wno-unbanged-strict-patterns
1644     :category:
1645
1646     This flag warns whenever you write a pattern that binds a variable whose
1647     type is unlifted, and yet the pattern is not a bang pattern nor a bare variable.
1648     See :ref:`glasgow-unboxed` for information about unlifted types.
1649
1650 .. ghc-flag:: -Wmissing-home-modules
1651     :shortdesc: warn when encountering a home module imported, but not listed
1652         on the command line. Useful for cabal to ensure GHC won't pick
1653         up modules, not listed neither in ``exposed-modules``, nor in
1654         ``other-modules``.
1655     :type: dynamic
1656     :reverse: -Wno-missing-home-modules
1657     :category:
1658
1659     :since: 8.2
1660
1661     When a module provided by the package currently being compiled
1662     (i.e. the "home" package) is imported, but not explicitly listed in
1663     command line as a target. Useful for Cabal to ensure GHC won't
1664     pick up modules, not listed neither in ``exposed-modules``, nor in
1665     ``other-modules``.
1666
1667 .. ghc-flag:: -Wpartial-fields
1668     :shortdesc: warn when defining a partial record field.
1669     :type: dynamic
1670     :reverse: -Wno-partial-fields
1671     :category:
1672
1673     :since: 8.4
1674
1675     The option :ghc-flag:`-Wpartial-fields` warns about record fields that could
1676     fail when accessed via a lacking constructor. The function ``f`` below will
1677     fail when applied to ``Bar``, so the compiler will emit a warning at its
1678     definition when :ghc-flag:`-Wpartial-fields` is enabled.
1679
1680     The warning is suppressed if the field name begins with an underscore. ::
1681
1682         data Foo = Foo { f :: Int } | Bar
1683
1684 If you're feeling really paranoid, the :ghc-flag:`-dcore-lint` option is a good choice.
1685 It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
1686 sanity, not yours.)