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