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