Print which warning-flag controls an emitted warning
[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:`-Wdeprecated-flags`
21     * :ghc-flag:`-Wunrecognised-pragmas`
22     * :ghc-flag:`-Wduplicate-constraints`
23     * :ghc-flag:`-Wduplicate-exports`
24     * :ghc-flag:`-Woverflowed-literals`
25     * :ghc-flag:`-Wempty-enumerations`
26     * :ghc-flag:`-Wmissing-fields`
27     * :ghc-flag:`-Wmissing-methods`
28     * :ghc-flag:`-Wwrong-do-bind`
29     * :ghc-flag:`-Wunsupported-calling-conventions`
30     * :ghc-flag:`-Wdodgy-foreign-imports`
31     * :ghc-flag:`-Winline-rule-shadowing`
32     * :ghc-flag:`-Wunsupported-llvm-version`
33     * :ghc-flag:`-Wtabs`
34     * :ghc-flag:`-Wunrecognised-warning-flags`
35
36 The following flags are simple ways to select standard "packages" of warnings:
37
38 .. ghc-flag:: -W
39
40     Provides the standard warnings plus
41
42     .. hlist::
43         :columns: 3
44
45         * :ghc-flag:`-Wunused-binds`
46         * :ghc-flag:`-Wunused-matches`
47         * :ghc-flag:`-Wunused-foralls`
48         * :ghc-flag:`-Wunused-imports`
49         * :ghc-flag:`-Wincomplete-patterns`
50         * :ghc-flag:`-Wdodgy-exports`
51         * :ghc-flag:`-Wdodgy-imports`
52
53 .. ghc-flag:: -Wall
54
55     Turns on all warning options that indicate potentially suspicious
56     code. The warnings that are *not* enabled by :ghc-flag:`-Wall` are
57
58     .. hlist::
59         :columns: 3
60
61         * :ghc-flag:`-Wincomplete-uni-patterns`
62         * :ghc-flag:`-Wincomplete-record-updates`
63         * :ghc-flag:`-Wmonomorphism-restriction`
64         * :ghc-flag:`-Wimplicit-prelude`
65         * :ghc-flag:`-Wmissing-local-signatures`
66         * :ghc-flag:`-Wmissing-exported-signatures`
67         * :ghc-flag:`-Wmissing-import-lists`
68         * :ghc-flag:`-Widentities`
69
70 .. ghc-flag:: -Wcompat
71
72     Turns on warnings that will be enabled by default in the future, but remain
73     off in normal compilations for the time being. This allows library authors
74     eager to make their code future compatible to adapt to new features before
75     they even generate warnings.
76
77     This currently enables
78
79     .. hlist::
80         :columns: 3
81
82         * :ghc-flag:`-Wmissing-monadfail-instances`
83         * :ghc-flag:`-Wsemigroup`
84         * :ghc-flag:`-Wnoncanonical-monoid-instances`
85
86 .. ghc-flag:: -Wno-compat
87
88     Disables all warnings enabled by :ghc-flag:`-Wcompat`.
89
90 .. ghc-flag:: -w
91
92     Turns off all warnings, including the standard ones and those that
93     :ghc-flag:`-Wall` doesn't enable.
94
95 .. ghc-flag:: -Werror
96
97     Makes any warning into a fatal error. Useful so that you don't miss
98     warnings when doing batch compilation.
99
100 .. ghc-flag:: -Wwarn
101
102     Warnings are treated only as warnings, not as errors. This is the
103     default, but can be useful to negate a :ghc-flag:`-Werror` flag.
104
105 When a warning is emitted, the specific warning flag which controls
106 it, as well as the group it belongs to, are shown.
107
108 .. ghc-flag:: -fshow-warning-groups
109
110     Name the group a warning flag belongs to.
111
112     This is enabled by default. Disable with ``-fno-show-warning-groups``.
113
114 The full set of warning options is described below. To turn off any
115 warning, simply give the corresponding ``-Wno-...`` option on the
116 command line. For backwards compatibility with GHC versions prior to 8.0,
117 all these warnings can still be controlled with ``-f(no-)warn-*`` instead
118 of ``-W(no-)*``.
119
120 .. ghc-flag:: -Wunrecognised-warning-flags
121
122     Enables warnings when the compiler encounters a ``-W...`` flag that is not
123     recognised.
124
125     This warning is on by default.
126
127 .. ghc-flag:: -Wtyped-holes
128
129     Determines whether the compiler reports typed holes warnings. Has no
130     effect unless typed holes errors are deferred until runtime. See
131     :ref:`typed-holes` and :ref:`defer-type-errors`
132
133     This warning is on by default.
134
135 .. ghc-flag:: -Wtype-errors
136
137     Causes a warning to be reported when a type error is deferred until
138     runtime. See :ref:`defer-type-errors`
139
140     This warning is on by default.
141
142 .. ghc-flag:: -fdefer-type-errors
143
144     :implies: :ghc-flag:`-fdefer-typed-holes`
145
146     Defer as many type errors as possible until runtime. At compile time
147     you get a warning (instead of an error). At runtime, if you use a
148     value that depends on a type error, you get a runtime error; but you
149     can run any type-correct parts of your code just fine. See
150     :ref:`defer-type-errors`
151
152 .. ghc-flag:: -fdefer-typed-holes
153
154     Defer typed holes errors until runtime. This will turn the errors
155     produced by :ref:`typed holes <typed-holes>` into warnings. Using a value
156     that depends on a typed hole produces a runtime error, the same as
157     :ghc-flag:`-fdefer-type-errors` (which implies this option). See :ref:`typed-holes`
158     and :ref:`defer-type-errors`.
159
160     Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
161
162 .. ghc-flag:: -Wpartial-type-signatures
163
164     Determines whether the compiler reports holes in partial type
165     signatures as warnings. Has no effect unless
166     :ghc-flag:`-XPartialTypeSignatures` is enabled, which controls whether
167     errors should be generated for holes in types or not. See
168     :ref:`partial-type-signatures`.
169
170     This warning is on by default.
171
172 .. ghc-flag:: -fhelpful-errors
173
174     When a name or package is not found in scope, make suggestions for
175     the name or package you might have meant instead.
176
177     This option is on by default.
178
179 .. ghc-flag:: -Wunrecognised-pragmas
180
181     Causes a warning to be emitted when a pragma that GHC doesn't
182     recognise is used. As well as pragmas that GHC itself uses, GHC also
183     recognises pragmas known to be used by other tools, e.g.
184     ``OPTIONS_HUGS`` and ``DERIVE``.
185
186     This option is on by default.
187
188 .. ghc-flag:: -Wmissed-specialisations
189               -Wall-missed-specialisations
190
191     Emits a warning if GHC cannot specialise an overloaded function, usually
192     because the function needs an ``INLINEABLE`` pragma. The "all" form reports
193     all such situations whereas the "non-all" form only reports when the
194     situation arises during specialisation of an imported function.
195
196     The "non-all" form is intended to catch cases where an imported function
197     that is marked as ``INLINEABLE`` (presumably to enable specialisation) cannot
198     be specialised as it calls other functions that are themselves not specialised.
199
200     Note that these warnings will not throw errors if used with :ghc-flag:`-Werror`.
201
202     These options are both off by default.
203
204 .. ghc-flag:: -Wwarnings-deprecations
205
206     .. index::
207        pair: deprecations; warnings
208
209     Causes a warning to be emitted when a module, function or type with
210     a ``WARNING`` or ``DEPRECATED pragma`` is used. See
211     :ref:`warning-deprecated-pragma` for more details on the pragmas.
212
213     This option is on by default.
214
215 .. ghc-flag:: -Wamp
216
217     .. index::
218        single: AMP
219        single: Applicative-Monad Proposal
220
221     This option is deprecated.
222
223     Caused a warning to be emitted when a definition was in conflict with
224     the AMP (Applicative-Monad proosal).
225
226 .. ghc-flag:: -Wnoncanonical-monad-instances
227
228     Warn if noncanonical ``Applicative`` or ``Monad`` instances
229     declarations are detected.
230
231     When this warning is enabled, the following conditions are verified:
232
233     In ``Monad`` instances declarations warn if any of the following
234     conditions does not hold:
235
236      * If ``return`` is defined it must be canonical (i.e. ``return = pure``).
237      * If ``(>>)`` is defined it must be canonical (i.e. ``(>>) = (*>)``).
238
239     Moreover, in ``Applicative`` instance declarations:
240
241      * Warn if ``pure`` is defined backwards (i.e. ``pure = return``).
242      * Warn if ``(*>)`` is defined backwards (i.e. ``(*>) = (>>)``).
243
244     This option is off by default.
245
246 .. ghc-flag:: -Wnoncanonical-monadfail-instances
247
248     Warn if noncanonical ``Monad`` or ``MonadFail`` instances
249     declarations are detected.
250
251     When this warning is enabled, the following conditions are verified:
252
253     In ``Monad`` instances declarations warn if any of the following
254     conditions does not hold:
255
256      * If ``fail`` is defined it must be canonical
257        (i.e. ``fail = Control.Monad.Fail.fail``).
258
259     Moreover, in ``MonadFail`` instance declarations:
260
261      * Warn if ``fail`` is defined backwards
262        (i.e. ``fail = Control.Monad.fail``).
263
264     See also :ghc-flag:`-Wmissing-monadfail-instances`.
265
266     This option is off by default.
267
268 .. ghc-flag:: -Wnoncanonical-monoid-instances
269
270     Warn if noncanonical ``Semigroup`` or ``Monoid`` instances
271     declarations are detected.
272
273     When this warning is enabled, the following conditions are verified:
274
275     In ``Monoid`` instances declarations warn if any of the following
276     conditions does not hold:
277
278      * If ``mappend`` is defined it must be canonical
279        (i.e. ``mappend = (Data.Semigroup.<>)``).
280
281     Moreover, in ``Semigroup`` instance declarations:
282
283      * Warn if ``(<>)`` is defined backwards (i.e. ``(<>) = mappend``).
284
285     This warning is off by default. However, it is part of the
286     :ghc-flag:`-Wcompat` option group.
287
288 .. ghc-flag:: -Wmissing-monadfail-instances
289
290     .. index::
291        single: MFP
292        single: MonadFail Proposal
293
294     Warn when a failable pattern is used in a do-block that does not have a
295     ``MonadFail`` instance.
296
297     See also :ghc-flag:`-Wnoncanonical-monadfail-instances`.
298
299     Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
300     default, but will be switched on in a future GHC release, as part of
301     the `MonadFail Proposal (MFP)
302     <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
303
304 .. ghc-flag:: -Wsemigroup
305
306     .. index::
307        single: semigroup; warning
308
309     Warn when definitions are in conflict with the future inclusion of
310     ``Semigroup`` into the standard typeclasses.
311
312      1. Instances of ``Monoid`` should also be instances of ``Semigroup``
313      2. The ``Semigroup`` operator ``(<>)`` will be in ``Prelude``, which
314         clashes with custom local definitions of such an operator
315
316     Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
317     default, but will be switched on in a future GHC release.
318
319 .. ghc-flag:: -Wdeprecated-flags
320
321     .. index::
322        single: deprecated flags
323
324     Causes a warning to be emitted when a deprecated command-line flag
325     is used.
326
327     This option is on by default.
328
329 .. ghc-flag:: -Wunsupported-calling-conventions
330
331     Causes a warning to be emitted for foreign declarations that use
332     unsupported calling conventions. In particular, if the ``stdcall``
333     calling convention is used on an architecture other than i386 then
334     it will be treated as ``ccall``.
335
336 .. ghc-flag:: -Wdodgy-foreign-imports
337
338     Causes a warning to be emitted for foreign imports of the following
339     form: ::
340
341         foreign import "f" f :: FunPtr t
342
343     on the grounds that it probably should be ::
344
345         foreign import "&f" f :: FunPtr t
346
347     The first form declares that \`f\` is a (pure) C function that takes
348     no arguments and returns a pointer to a C function with type \`t\`,
349     whereas the second form declares that \`f\` itself is a C function
350     with type \`t\`. The first declaration is usually a mistake, and one
351     that is hard to debug because it results in a crash, hence this
352     warning.
353
354 .. ghc-flag:: -Wdodgy-exports
355
356     Causes a warning to be emitted when a datatype ``T`` is exported
357     with all constructors, i.e. ``T(..)``, but is it just a type
358     synonym.
359
360     Also causes a warning to be emitted when a module is re-exported,
361     but that module exports nothing.
362
363 .. ghc-flag:: -Wdodgy-imports
364
365     Causes a warning to be emitted in the following cases:
366
367     -  When a datatype ``T`` is imported with all constructors, i.e.
368        ``T(..)``, but has been exported abstractly, i.e. ``T``.
369
370     -  When an ``import`` statement hides an entity that is not
371        exported.
372
373 .. ghc-flag:: -Woverflowed-literals
374
375     Causes a warning to be emitted if a literal will overflow, e.g.
376     ``300 :: Word8``.
377
378 .. ghc-flag:: -Wempty-enumerations
379
380     Causes a warning to be emitted if an enumeration is empty, e.g.
381     ``[5 .. 3]``.
382
383 .. ghc-flag:: -Wduplicate-constraints
384
385     .. index::
386        single: duplicate constraints, warning
387
388     Have the compiler warn about duplicate constraints in a type
389     signature. For example ::
390
391         f :: (Eq a, Show a, Eq a) => a -> a
392
393     The warning will indicate the duplicated ``Eq a`` constraint.
394
395     This option is now deprecated in favour of
396     :ghc-flag:`-Wredundant-constraints`.
397
398 .. ghc-flag:: -Wredundant-constraints
399
400     .. index::
401        single: redundant constraints, warning
402
403     Have the compiler warn about redundant constraints in a type
404     signature. In particular:
405
406     -  A redundant constraint within the type signature itself: ::
407
408             f :: (Eq a, Ord a) => a -> a
409
410        The warning will indicate the redundant ``Eq a`` constraint: it
411        is subsumed by the ``Ord a`` constraint.
412
413     -  A constraint in the type signature is not used in the code it
414        covers: ::
415
416             f :: Eq a => a -> a -> Bool
417             f x y = True
418
419        The warning will indicate the redundant ``Eq a`` constraint: : it
420        is not used by the definition of ``f``.)
421
422     Similar warnings are given for a redundant constraint in an instance
423     declaration.
424
425     This option is on by default. As usual you can suppress it on a
426     per-module basis with :ghc-flag:`-Wno-redundant-constraints`.
427     Occasionally you may specifically want a function to have a more
428     constrained signature than necessary, perhaps to leave yourself
429     wiggle-room for changing the implementation without changing the
430     API. In that case, you can suppress the warning on a per-function
431     basis, using a call in a dead binding. For example: ::
432
433         f :: Eq a => a -> a -> Bool
434         f x y = True
435         where
436             _ = x == x  -- Suppress the redundant-constraint warning for (Eq a)
437
438     Here the call to ``(==)`` makes GHC think that the ``(Eq a)``
439     constraint is needed, so no warning is issued.
440
441 .. ghc-flag:: -Wduplicate-exports
442
443     .. index::
444        single: duplicate exports, warning
445        single: export lists, duplicates
446
447     Have the compiler warn about duplicate entries in export lists. This
448     is useful information if you maintain large export lists, and want
449     to avoid the continued export of a definition after you've deleted
450     (one) mention of it in the export list.
451
452     This option is on by default.
453
454 .. ghc-flag:: -Whi-shadowing
455
456     .. index::
457        single: shadowing; interface files
458
459     Causes the compiler to emit a warning when a module or interface
460     file in the current directory is shadowing one with the same module
461     name in a library or other directory.
462
463 .. ghc-flag:: -Widentities
464
465     Causes the compiler to emit a warning when a Prelude numeric
466     conversion converts a type ``T`` to the same type ``T``; such calls are
467     probably no-ops and can be omitted. The functions checked for are:
468     ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.
469
470 .. ghc-flag:: -Wimplicit-prelude
471
472     .. index::
473        single: implicit prelude, warning
474
475     Have the compiler warn if the Prelude is implicitly imported. This
476     happens unless either the Prelude module is explicitly imported with
477     an ``import ... Prelude ...`` line, or this implicit import is
478     disabled (either by :ghc-flag:`-XNoImplicitPrelude` or a
479     ``LANGUAGE NoImplicitPrelude`` pragma).
480
481     Note that no warning is given for syntax that implicitly refers to
482     the Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
483     refers to the Prelude. For example, no warning is given when ``368``
484     means ``Prelude.fromInteger (368::Prelude.Integer)`` (where
485     ``Prelude`` refers to the actual Prelude module, regardless of the
486     imports of the module being compiled).
487
488     This warning is off by default.
489
490 .. ghc-flag:: -Wincomplete-patterns
491               -Wincomplete-uni-patterns
492
493     .. index::
494        single: incomplete patterns, warning
495        single: patterns, incomplete
496
497     The option :ghc-flag:`-Wincomplete-patterns` warns about places where a
498     pattern-match might fail at runtime. The function ``g`` below will
499     fail when applied to non-empty lists, so the compiler will emit a
500     warning about this when :ghc-flag:`-Wincomplete-patterns` is enabled. ::
501
502         g [] = 2
503
504     This option isn't enabled by default because it can be a bit noisy,
505     and it doesn't always indicate a bug in the program. However, it's
506     generally considered good practice to cover all the cases in your
507     functions, and it is switched on by :ghc-flag:`-W`.
508
509     The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar, except that
510     it applies only to lambda-expressions and pattern bindings,
511     constructs that only allow a single pattern: ::
512
513         h = \[] -> 2
514         Just k = f y
515
516 .. ghc-flag:: -Wincomplete-record-updates
517
518     .. index::
519        single: incomplete record updates, warning
520        single: record updates, incomplete
521
522     The function ``f`` below will fail when applied to ``Bar``, so the
523     compiler will emit a warning about this when
524     :ghc-flag:`-Wincomplete-record-updates` is enabled. ::
525
526         data Foo = Foo { x :: Int }
527                  | Bar
528
529         f :: Foo -> Foo
530         f foo = foo { x = 6 }
531
532     This option isn't enabled by default because it can be very noisy,
533     and it often doesn't indicate a bug in the program.
534
535 .. ghc-flag:: -Wmissing-fields
536
537     .. index::
538        single: missing fields, warning
539        single: fields, missing
540
541     This option is on by default, and warns you whenever the
542     construction of a labelled field constructor isn't complete, missing
543     initialisers for one or more fields. While not an error (the missing
544     fields are initialised with bottoms), it is often an indication of a
545     programmer error.
546
547 .. ghc-flag:: -Wmissing-import-lists
548
549     .. index::
550        single: missing import lists, warning
551        single: import lists, missing
552
553     This flag warns if you use an unqualified ``import`` declaration
554     that does not explicitly list the entities brought into scope. For
555     example ::
556
557         module M where
558           import X( f )
559           import Y
560           import qualified Z
561           p x = f x x
562
563     The :ghc-flag:`-Wmissing-import-lists` flag will warn about the import of
564     ``Y`` but not ``X`` If module ``Y`` is later changed to export (say) ``f``,
565     then the reference to ``f`` in ``M`` will become ambiguous. No warning is
566     produced for the import of ``Z`` because extending ``Z``\'s exports would be
567     unlikely to produce ambiguity in ``M``.
568
569 .. ghc-flag:: -Wmissing-methods
570
571     .. index::
572        single: missing methods, warning
573        single: methods, missing
574
575     This option is on by default, and warns you whenever an instance
576     declaration is missing one or more methods, and the corresponding
577     class declaration has no default declaration for them.
578
579     The warning is suppressed if the method name begins with an
580     underscore. Here's an example where this is useful: ::
581
582         class C a where
583             _simpleFn :: a -> String
584             complexFn :: a -> a -> String
585             complexFn x y = ... _simpleFn ...
586
587     The idea is that: (a) users of the class will only call
588     ``complexFn``; never ``_simpleFn``; and (b) instance declarations
589     can define either ``complexFn`` or ``_simpleFn``.
590
591     The ``MINIMAL`` pragma can be used to change which combination of
592     methods will be required for instances of a particular class. See
593     :ref:`minimal-pragma`.
594
595 .. ghc-flag:: -Wmissing-signatures
596
597     .. index::
598        single: type signatures, missing
599
600     If you would like GHC to check that every top-level function/value
601     has a type signature, use the :ghc-flag:`-Wmissing-signatures` option.
602     As part of the warning GHC also reports the inferred type. The
603     option is off by default.
604
605 .. ghc-flag:: -Wmissing-exported-sigs
606
607     .. index::
608        single: type signatures, missing
609
610     This option is now deprecated in favour of
611     :ghc-flag:`-Wmissing-exported-signatures`.
612
613 .. ghc-flag:: -Wmissing-exported-signatures
614
615     .. index::
616        single: type signatures, missing
617
618     If you would like GHC to check that every exported top-level
619     function/value has a type signature, but not check unexported
620     values, use the :ghc-flag:`-Wmissing-exported-signatures`
621     option. This option takes precedence over
622     :ghc-flag:`-Wmissing-signatures`. As part of the warning GHC also
623     reports the inferred type. The option is off by default.
624
625 .. ghc-flag:: -Wmissing-local-sigs
626
627     .. index::
628        single: type signatures, missing
629
630     This option is now deprecated in favour of
631     :ghc-flag:`-Wmissing-local-signatures`.
632
633 .. ghc-flag:: -Wmissing-local-signatures
634
635     .. index::
636        single: type signatures, missing
637
638     If you use the :ghc-flag:`-Wmissing-local-signatures` flag GHC
639     will warn you about any polymorphic local bindings. As part of the
640     warning GHC also reports the inferred type. The option is off by
641     default.
642
643 .. ghc-flag:: -Wmissing-pattern-synonym-signatures
644
645     .. index::
646          single: type signatures, missing, pattern synonyms
647
648     If you would like GHC to check that every pattern synonym has a
649     type signature, use the
650     :ghc-flag:`-Wmissing-pattern-synonym-signatures` option. If this
651     option is used in conjunction with
652     :ghc-flag:`-Wmissing-exported-signatures` then only exported pattern
653     synonyms must have a type signature. GHC also reports the inferred
654     type. This option is off by default.
655
656 .. ghc-flag:: -Wname-shadowing
657
658     .. index::
659        single: shadowing, warning
660
661     This option causes a warning to be emitted whenever an inner-scope
662     value has the same name as an outer-scope value, i.e. the inner
663     value shadows the outer one. This can catch typographical errors
664     that turn into hard-to-find bugs, e.g., in the inadvertent capture
665     of what would be a recursive call in
666     ``f = ... let f = id in ... f ...``.
667
668     The warning is suppressed for names beginning with an underscore.
669     For example ::
670
671         f x = do { _ignore <- this; _ignore <- that; return (the other) }
672
673 .. ghc-flag:: -Worphans
674
675     .. index::
676        single: orphan instances, warning
677        single: orphan rules, warning
678
679     These flags cause a warning to be emitted whenever the module
680     contains an "orphan" instance declaration or rewrite rule. An
681     instance declaration is an orphan if it appears in a module in which
682     neither the class nor the type being instanced are declared in the
683     same module. A rule is an orphan if it is a rule for a function
684     declared in another module. A module containing any orphans is
685     called an orphan module.
686
687     The trouble with orphans is that GHC must pro-actively read the
688     interface files for all orphan modules, just in case their instances
689     or rules play a role, whether or not the module's interface would
690     otherwise be of any use. See :ref:`orphan-modules` for details.
691
692     The flag :ghc-flag:`-Worphans` warns about user-written orphan rules or
693     instances.
694
695 .. ghc-flag:: -Woverlapping-patterns
696
697     .. index::
698        single: overlapping patterns, warning
699        single: patterns, overlapping
700
701     By default, the compiler will warn you if a set of patterns are
702     overlapping, e.g., ::
703
704         f :: String -> Int
705         f []     = 0
706         f (_:xs) = 1
707         f "2"    = 2
708
709     where the last pattern match in ``f`` won't ever be reached, as the
710     second pattern overlaps it. More often than not, redundant patterns
711     is a programmer mistake/error, so this option is enabled by default.
712
713 .. ghc-flag:: -Wtabs
714
715     .. index::
716        single: tabs, warning
717
718     Have the compiler warn if there are tabs in your source file.
719
720 .. ghc-flag:: -Wtype-defaults
721
722     .. index::
723        single: defaulting mechanism, warning
724
725     Have the compiler warn/inform you where in your source the Haskell
726     defaulting mechanism for numeric types kicks in. This is useful
727     information when converting code from a context that assumed one
728     default into one with another, e.g., the â€˜default default’ for
729     Haskell 1.4 caused the otherwise unconstrained value ``1`` to be
730     given the type ``Int``, whereas Haskell 98 and later defaults it to
731     ``Integer``. This may lead to differences in performance and
732     behaviour, hence the usefulness of being non-silent about this.
733
734     This warning is off by default.
735
736 .. ghc-flag:: -Wmonomorphism-restriction
737
738     .. index::
739        single: monomorphism restriction, warning
740
741     Have the compiler warn/inform you where in your source the Haskell
742     Monomorphism Restriction is applied. If applied silently the MR can
743     give rise to unexpected behaviour, so it can be helpful to have an
744     explicit warning that it is being applied.
745
746     This warning is off by default.
747
748 .. ghc-flag:: -Wunsupported-llvm-version
749
750     Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.
751
752 .. ghc-flag:: -Wunticked-promoted-constructors
753
754     .. index::
755        single: promoted constructor, warning
756
757     Warn if a promoted data constructor is used without a tick preceding
758     its name.
759
760     For example: ::
761
762         data Nat = Succ Nat | Zero
763
764         data Vec n s where
765           Nil  :: Vec Zero a
766           Cons :: a -> Vec n a -> Vec (Succ n) a
767
768     Will raise two warnings because ``Zero`` and ``Succ`` are not
769     written as ``'Zero`` and ``'Succ``.
770
771     This warning is is enabled by default in :ghc-flag:`-Wall` mode.
772
773 .. ghc-flag:: -Wunused-binds
774
775     .. index::
776        single: unused binds, warning
777        single: binds, unused
778
779     Report any function definitions (and local bindings) which are
780     unused. An alias for
781
782     -  :ghc-flag:`-Wunused-top-binds`
783     -  :ghc-flag:`-Wunused-local-binds`
784     -  :ghc-flag:`-Wunused-pattern-binds`
785
786 .. ghc-flag:: -Wunused-top-binds
787
788     .. index::
789        single: unused binds, warning
790        single: binds, unused
791
792     Report any function definitions which are unused.
793
794     More precisely, warn if a binding brings into scope a variable that
795     is not used, except if the variable's name starts with an
796     underscore. The "starts-with-underscore" condition provides a way to
797     selectively disable the warning.
798
799     A variable is regarded as "used" if
800
801     -  It is exported, or
802
803     -  It appears in the right hand side of a binding that binds at
804        least one used variable that is used
805
806     For example: ::
807
808         module A (f) where
809         f = let (p,q) = rhs1 in t p  -- No warning: q is unused, but is locally bound
810         t = rhs3                     -- No warning: f is used, and hence so is t
811         g = h x                      -- Warning: g unused
812         h = rhs2                     -- Warning: h is only used in the
813                                      -- right-hand side of another unused binding
814         _w = True                    -- No warning: _w starts with an underscore
815
816 .. ghc-flag:: -Wunused-local-binds
817
818     .. index::
819        single: unused binds, warning
820        single: binds, unused
821
822     Report any local definitions which are unused. For example: ::
823
824         module A (f) where
825         f = let (p,q) = rhs1 in t p  -- Warning: q is unused
826         g = h x                      -- No warning: g is unused, but is a top-level binding
827
828 .. ghc-flag:: -Wunused-pattern-binds
829
830     .. index::
831        single: unused binds, warning
832        single: binds, unused
833
834     Warn if a pattern binding binds no variables at all, unless it is a
835     lone, possibly-banged, wild-card pattern. For example: ::
836
837         Just _ = rhs3    -- Warning: unused pattern binding
838         (_, _) = rhs4    -- Warning: unused pattern binding
839         _  = rhs3        -- No warning: lone wild-card pattern
840         !_ = rhs4        -- No warning: banged wild-card pattern; behaves like seq
841
842     The motivation for allowing lone wild-card patterns is they are not
843     very different from ``_v = rhs3``, which elicits no warning; and
844     they can be useful to add a type constraint, e.g. ``_ = x::Int``. A
845     lone banged wild-card pattern is useful as an alternative (to
846     ``seq``) way to force evaluation.
847
848 .. ghc-flag:: -Wunused-imports
849
850     .. index::
851        single: unused imports, warning
852        single: imports, unused
853
854     Report any modules that are explicitly imported but never used.
855     However, the form ``import M()`` is never reported as an unused
856     import, because it is a useful idiom for importing instance
857     declarations, which are anonymous in Haskell.
858
859 .. ghc-flag:: -Wunused-matches
860
861     .. index::
862        single: unused matches, warning
863        single: matches, unused
864
865     Report all unused variables which arise from term-level pattern matches,
866     including patterns consisting of a single variable. For instance
867     ``f x y = []`` would report ``x`` and ``y`` as unused. The warning
868     is suppressed if the variable name begins with an underscore, thus: ::
869
870         f _x = True
871
872     Note that :ghc-flag:`-Wunused-matches` does not warn about variables which
873     arise from type-level patterns, as found in type family and data family
874     instances. This must be enabled separately through the
875     :ghc-flag:`-Wunused-type-patterns` flag.
876
877 .. ghc-flag:: -Wunused-do-bind
878
879     .. index::
880        single: unused do binding, warning
881        single: do binding, unused
882
883     Report expressions occurring in ``do`` and ``mdo`` blocks that
884     appear to silently throw information away. For instance
885     ``do { mapM popInt xs ; return 10 }`` would report the first
886     statement in the ``do`` block as suspicious, as it has the type
887     ``StackM [Int]`` and not ``StackM ()``, but that ``[Int]`` value is
888     not bound to anything. The warning is suppressed by explicitly
889     mentioning in the source code that your program is throwing
890     something away: ::
891
892         do { _ <- mapM popInt xs ; return 10 }
893
894     Of course, in this particular situation you can do even better: ::
895
896         do { mapM_ popInt xs ; return 10 }
897
898 .. ghc-flag:: -Wunused-type-patterns
899
900     .. index::
901        single: unused type patterns, warning
902        single: type patterns, unused
903
904     Report all unused type variables which arise from patterns in type family
905     and data family instances. For instance: ::
906
907         type instance F x y = []
908
909     would report ``x`` and ``y`` as unused. The warning is suppressed if the
910     type variable name begins with an underscore, like so: ::
911
912         type instance F _x _y = []
913
914     Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-variables` is
915     not implied by :ghc-flag:`-Wall`. The rationale for this decision is that
916     unlike term-level pattern names, type names are often chosen expressly for
917     documentation purposes, so using underscores in type names can make the
918     documentation harder to read.
919
920 .. ghc-flag:: -Wunused-foralls
921
922     .. index::
923        single: unused foralls, warning
924        single: foralls, unused
925
926     Report all unused type variables which arise from explicit, user-written
927     ``forall`` statements. For instance: ::
928
929         g :: forall a b c. (b -> b)
930
931     would report ``a`` and ``c`` as unused.
932
933 .. ghc-flag:: -Wwrong-do-bind
934
935     .. index::
936        single: apparently erroneous do binding, warning
937        single: do binding, apparently erroneous
938
939     Report expressions occurring in ``do`` and ``mdo`` blocks that
940     appear to lack a binding. For instance
941     ``do { return (popInt 10) ; return 10 }`` would report the first
942     statement in the ``do`` block as suspicious, as it has the type
943     ``StackM (StackM Int)`` (which consists of two nested applications
944     of the same monad constructor), but which is not then "unpacked" by
945     binding the result. The warning is suppressed by explicitly
946     mentioning in the source code that your program is throwing
947     something away: ::
948
949         do { _ <- return (popInt 10) ; return 10 }
950
951     For almost all sensible programs this will indicate a bug, and you
952     probably intended to write: ::
953
954         do { popInt 10 ; return 10 }
955
956 .. ghc-flag:: -Winline-rule-shadowing
957
958     Warn if a rewrite RULE might fail to fire because the function might
959     be inlined before the rule has a chance to fire. See
960     :ref:`rules-inline`.
961
962 If you're feeling really paranoid, the :ghc-flag:`-dcore-lint` option is a good choice.
963 It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
964 sanity, not yours.)
965