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