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