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