using-warnings.rst 50.8 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
.. _options-sanity:

Warnings and sanity-checking
----------------------------

.. index::
   single: sanity-checking options
   single: warnings

GHC has a number of options that select which types of non-fatal error
messages, otherwise known as warnings, can be generated during
compilation. By default, you get a standard set of warnings which are
generally likely to indicate bugs in your program. These are:

15
16
17
18
19
.. hlist::
    :columns: 3

    * :ghc-flag:`-Woverlapping-patterns`
    * :ghc-flag:`-Wwarnings-deprecations`
20
    * :ghc-flag:`-Wdeprecations`
21
22
23
24
25
26
27
28
29
30
31
32
33
34
    * :ghc-flag:`-Wdeprecated-flags`
    * :ghc-flag:`-Wunrecognised-pragmas`
    * :ghc-flag:`-Wduplicate-constraints`
    * :ghc-flag:`-Wduplicate-exports`
    * :ghc-flag:`-Woverflowed-literals`
    * :ghc-flag:`-Wempty-enumerations`
    * :ghc-flag:`-Wmissing-fields`
    * :ghc-flag:`-Wmissing-methods`
    * :ghc-flag:`-Wwrong-do-bind`
    * :ghc-flag:`-Wunsupported-calling-conventions`
    * :ghc-flag:`-Wdodgy-foreign-imports`
    * :ghc-flag:`-Winline-rule-shadowing`
    * :ghc-flag:`-Wunsupported-llvm-version`
    * :ghc-flag:`-Wtabs`
35
    * :ghc-flag:`-Wunrecognised-warning-flags`
36
37
38
39

The following flags are simple ways to select standard "packages" of warnings:

.. ghc-flag:: -W
40
41
42
43
    :shortdesc: enable normal warnings
    :type: dynamic
    :reverse: -w
    :category:
44

45
46
47
48
49
50
51
    Provides the standard warnings plus

    .. hlist::
        :columns: 3

        * :ghc-flag:`-Wunused-binds`
        * :ghc-flag:`-Wunused-matches`
52
        * :ghc-flag:`-Wunused-foralls`
53
54
55
56
        * :ghc-flag:`-Wunused-imports`
        * :ghc-flag:`-Wincomplete-patterns`
        * :ghc-flag:`-Wdodgy-exports`
        * :ghc-flag:`-Wdodgy-imports`
Richard Eisenberg's avatar
Richard Eisenberg committed
57
        * :ghc-flag:`-Wunbanged-strict-patterns`
58
59

.. ghc-flag:: -Wall
60
61
62
63
    :shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
    :type: dynamic
    :reverse: -w
    :category:
64
65

    Turns on all warning options that indicate potentially suspicious
66
    code. The warnings that are *not* enabled by :ghc-flag:`-Wall` are
67
68
69
70
71
72
73
74

    .. hlist::
        :columns: 3

        * :ghc-flag:`-Wincomplete-uni-patterns`
        * :ghc-flag:`-Wincomplete-record-updates`
        * :ghc-flag:`-Wmonomorphism-restriction`
        * :ghc-flag:`-Wimplicit-prelude`
manav's avatar
manav committed
75
76
        * :ghc-flag:`-Wmissing-local-signatures`
        * :ghc-flag:`-Wmissing-exported-signatures`
77
        * :ghc-flag:`-Wmissing-export-lists`
78
        * :ghc-flag:`-Wmissing-import-lists`
Yuras's avatar
Yuras committed
79
        * :ghc-flag:`-Wmissing-home-modules`
80
        * :ghc-flag:`-Widentities`
81
        * :ghc-flag:`-Wredundant-constraints`
82
        * :ghc-flag:`-Wpartial-fields`
83

Ben Gamari's avatar
Ben Gamari committed
84
85
86
87
88
89
90
.. ghc-flag:: -Weverything
    :shortdesc: enable all warnings supported by GHC
    :type: dynamic
    :category:

    Turns on every single warning supported by the compiler.

91
.. ghc-flag:: -Wcompat
92
93
94
95
96
    :shortdesc: enable future compatibility warnings
        (details in :ref:`options-sanity`)
    :type: dynamic
    :reverse: -Wno-compat
    :category:
quchen's avatar
quchen committed
97
98
99
100
101
102

    Turns on warnings that will be enabled by default in the future, but remain
    off in normal compilations for the time being. This allows library authors
    eager to make their code future compatible to adapt to new features before
    they even generate warnings.

103
104
105
106
107
    This currently enables

    .. hlist::
        :columns: 3

108
        * :ghc-flag:`-Wmissing-monadfail-instances`
109
110
        * :ghc-flag:`-Wsemigroup`
        * :ghc-flag:`-Wnoncanonical-monoid-instances`
quchen's avatar
quchen committed
111

112
.. ghc-flag:: -Wno-compat
113
114
115
116
    :shortdesc: Disables all warnings enabled by :ghc-flag:`-Wcompat`.
    :type: dynamic
    :reverse: -Wcompat
    :category:
quchen's avatar
quchen committed
117

118
    Disables all warnings enabled by :ghc-flag:`-Wcompat`.
quchen's avatar
quchen committed
119

120
.. ghc-flag:: -w
121
122
123
    :shortdesc: disable all warnings
    :type: dynamic
    :category:
124
125

    Turns off all warnings, including the standard ones and those that
126
    :ghc-flag:`-Wall` doesn't enable.
127

128
129
130
These options control which warnings are considered fatal and cause compilation
to abort.

131
.. ghc-flag:: -Werror
132
133
134
135
    :shortdesc: make warnings fatal
    :type: dynamic
    :reverse: -Wwarn
    :category:
136
137
138
139

    Makes any warning into a fatal error. Useful so that you don't miss
    warnings when doing batch compilation.

140
.. ghc-flag:: -Werror=⟨wflag⟩
141
142
143
144
    :shortdesc: make a specific warning fatal
    :type: dynamic
    :reverse: -Wwarn=⟨wflag⟩
    :category:
145
    :noindex:
146
147
148
149
150
151

    :implies: ``-W<wflag>``

    Makes a specific warning into a fatal error. The warning will be enabled if
    it hasn't been enabled yet.

152
.. ghc-flag:: -Wwarn
153
154
155
156
    :shortdesc: make warnings non-fatal
    :type: dynamic
    :reverse: -Werror
    :category:
157
158

    Warnings are treated only as warnings, not as errors. This is the
159
    default, but can be useful to negate a :ghc-flag:`-Werror` flag.
160

161
.. ghc-flag:: -Wwarn=⟨wflag⟩
162
163
164
165
    :shortdesc: make a specific warning non-fatal
    :type: dynamic
    :reverse: -Werror=⟨wflag⟩
    :category:
166
    :noindex:
167
168
169
170
171
172

    Causes a specific warning to be treated as normal warning, not fatal error.

    Note that it doesn't fully negate the effects of ``-Werror=<wflag>`` - the
    warning will still be enabled.

173
When a warning is emitted, the specific warning flag which controls
174
it is shown.
175
176

.. ghc-flag:: -fshow-warning-groups
177
178
179
180
    :shortdesc: show which group an emitted warning belongs to.
    :type: dynamic
    :reverse: -fno-show-warning-groups
    :category:
181

182
183
    When showing which flag controls a warning, also show the
    respective warning group flag(s) that warning is contained in.
184

185
    This option is off by default.
186

187
The full set of warning options is described below. To turn off any
188
189
190
191
warning, simply give the corresponding ``-Wno-...`` option on the
command line. For backwards compatibility with GHC versions prior to 8.0,
all these warnings can still be controlled with ``-f(no-)warn-*`` instead
of ``-W(no-)*``.
192

193
.. ghc-flag:: -Wunrecognised-warning-flags
194
195
196
197
198
    :shortdesc: throw a warning when an unreconised ``-W...`` flag is
        encountered on the command line.
    :type: dynamic
    :reverse: -Wno-unrecognised-warning-flags
    :category:
199
200
201
202
203
204

    Enables warnings when the compiler encounters a ``-W...`` flag that is not
    recognised.

    This warning is on by default.

205
.. ghc-flag:: -Wtyped-holes
206
207
208
209
210
211
    :shortdesc: Report warnings when :ref:`typed hole <typed-holes>` errors are
        :ref:`deferred until runtime <defer-type-errors>`. See
        :ghc-flag:`-fdefer-typed-holes`.
    :type: dynamic
    :reverse: -Wno-typed-holes
    :category:
212
213
214
215
216
217
218

    Determines whether the compiler reports typed holes warnings. Has no
    effect unless typed holes errors are deferred until runtime. See
    :ref:`typed-holes` and :ref:`defer-type-errors`

    This warning is on by default.

219
220
221
222
223
224
225
.. ghc-flag:: -Wdeferred-type-errors
    :shortdesc: Report warnings when :ref:`deferred type errors
        <defer-type-errors>` are enabled. This option is enabled by
        default. See :ghc-flag:`-fdefer-type-errors`.
    :type: dynamic
    :reverse: -Wno-deferred-type-errors
    :category:
226
227
228
229
230
231

    Causes a warning to be reported when a type error is deferred until
    runtime. See :ref:`defer-type-errors`

    This warning is on by default.

232
.. ghc-flag:: -fdefer-type-errors
233
234
235
236
237
238
239
240
    :shortdesc: Turn type errors into warnings, :ref:`deferring the error until
        runtime <defer-type-errors>`. Implies
        :ghc-flag:`-fdefer-typed-holes` and
        :ghc-flag:`-fdefer-out-of-scope-variables`.
        See also :ghc-flag:`-Wdeferred-type-errors`
    :type: dynamic
    :reverse: -fno-defer-type-errors
    :category:
241

242
    :implies: :ghc-flag:`-fdefer-typed-holes`, :ghc-flag:`-fdefer-out-of-scope-variables`
Ben Gamari's avatar
Ben Gamari committed
243

244
245
246
247
248
249
    Defer as many type errors as possible until runtime. At compile time
    you get a warning (instead of an error). At runtime, if you use a
    value that depends on a type error, you get a runtime error; but you
    can run any type-correct parts of your code just fine. See
    :ref:`defer-type-errors`

250
.. ghc-flag:: -fdefer-typed-holes
251
252
253
254
255
256
257
    :shortdesc: Convert :ref:`typed hole <typed-holes>` errors into warnings,
        :ref:`deferring the error until runtime <defer-type-errors>`.
        Implied by :ghc-flag:`-fdefer-type-errors`.
        See also :ghc-flag:`-Wtyped-holes`.
    :type: dynamic
    :reverse: -fno-defer-typed-holes
    :category:
258

259
260
    Defer typed holes errors (errors about names with a leading underscore
    (e.g., “_”, “_foo”, “_bar”)) until runtime. This will turn the errors
261
262
    produced by :ref:`typed holes <typed-holes>` into warnings. Using a value
    that depends on a typed hole produces a runtime error, the same as
263
    :ghc-flag:`-fdefer-type-errors` (which implies this option). See :ref:`typed-holes`
264
265
    and :ref:`defer-type-errors`.

266
    Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
267

268
.. ghc-flag:: -fdefer-out-of-scope-variables
269
270
271
272
273
274
    :shortdesc: Convert variable out of scope variables errors into warnings.
        Implied by :ghc-flag:`-fdefer-type-errors`.
        See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
    :type: dynamic
    :reverse: -fno-defer-out-of-scope-variables
    :category:
275

Ben Gamari's avatar
Ben Gamari committed
276
    Defer variable out-of-scope errors (errors about names without a leading underscore)
277
278
279
280
281
282
283
    until runtime. This will turn variable-out-of-scope errors into warnings.
    Using a value that depends on a typed hole produces a runtime error,
    the same as :ghc-flag:`-fdefer-type-errors` (which implies this option).
    See :ref:`typed-holes` and :ref:`defer-type-errors`.

    Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.

Ben Gamari's avatar
Ben Gamari committed
284
.. ghc-flag:: -Wdeferred-out-of-scope-variables
285
    :shortdesc: Report warnings when variable out-of-scope errors are
Ben Gamari's avatar
Ben Gamari committed
286
        :ref:`deferred until runtime <defer-type-errors>`.
287
288
289
290
        See :ghc-flag:`-fdefer-out-of-scope-variables`.
    :type: dynamic
    :reverse: -Wno-deferred-out-of-scope-variables
    :category:
Ben Gamari's avatar
Ben Gamari committed
291
292
293

    Warn when a deferred out-of-scope variable is encountered.

294
.. ghc-flag:: -Wpartial-type-signatures
295
296
297
298
299
300
301
302
    :shortdesc: warn about holes in partial type signatures when
        :ghc-flag:`-XPartialTypeSignatures` is enabled. Not applicable when
        :ghc-flag:`-XPartialTypesignatures` is not enabled, in which case
        errors are generated for such holes. See
        :ref:`partial-type-signatures`.
    :type: dynamic
    :reverse: -Wno-partial-type-signatures
    :category:
303
304
305

    Determines whether the compiler reports holes in partial type
    signatures as warnings. Has no effect unless
306
    :ghc-flag:`-XPartialTypeSignatures` is enabled, which controls whether
307
308
309
310
311
    errors should be generated for holes in types or not. See
    :ref:`partial-type-signatures`.

    This warning is on by default.

312
.. ghc-flag:: -fhelpful-errors
313
314
315
316
    :shortdesc: Make suggestions for mis-spelled names.
    :type: dynamic
    :reverse: -fno-helpful-errors
    :category:
317
318
319
320
321
322

    When a name or package is not found in scope, make suggestions for
    the name or package you might have meant instead.

    This option is on by default.

323
.. ghc-flag:: -Wunrecognised-pragmas
324
325
326
327
    :shortdesc: warn about uses of pragmas that GHC doesn't recognise
    :type: dynamic
    :reverse: -Wno-unrecognised-pragmas
    :category:
328
329
330
331
332
333
334
335

    Causes a warning to be emitted when a pragma that GHC doesn't
    recognise is used. As well as pragmas that GHC itself uses, GHC also
    recognises pragmas known to be used by other tools, e.g.
    ``OPTIONS_HUGS`` and ``DERIVE``.

    This option is on by default.

336
.. ghc-flag:: -Wmissed-specialisations
337
338
339
340
341
    :shortdesc: warn when specialisation of an imported, overloaded function
        fails.
    :type: dynamic
    :reverse: -Wno-missed-specialisations
    :category:
342

343
    Emits a warning if GHC cannot specialise an overloaded function, usually
344
    because the function needs an ``INLINABLE`` pragma. Reports when the
345
346
    situation arises during specialisation of an imported function.

347
348
349
350
    This form is intended to catch cases where an imported function
    that is marked as ``INLINABLE`` (presumably to enable specialisation)
    cannot be specialised as it calls other functions that are themselves not
    specialised.
351

352
353
    Note that this warning will not throw errors if used with
    :ghc-flag:`-Werror`.
354

355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
    This option is off by default.

.. ghc-flag:: -Wall-missed-specialisations
    :shortdesc: warn when specialisation of any overloaded function fails.
    :type: dynamic
    :reverse: -Wno-all-missed-specialisations
    :category:

    Emits a warning if GHC cannot specialise an overloaded function, usually
    because the function needs an ``INLINABLE`` pragma. Reports
    all such situations.

    Note that this warning will not throw errors if used with
    :ghc-flag:`-Werror`.

    This option is off by default.
371

372
.. ghc-flag:: -Wwarnings-deprecations
373
374
375
376
377
    :shortdesc: warn about uses of functions & types that have warnings or
        deprecated pragmas
    :type: dynamic
    :reverse: -Wno-warnings-deprecations
    :category:
378

379
    .. index::
380
       pair: deprecations; warnings
381
382
383
384
385
386
387

    Causes a warning to be emitted when a module, function or type with
    a ``WARNING`` or ``DEPRECATED pragma`` is used. See
    :ref:`warning-deprecated-pragma` for more details on the pragmas.

    This option is on by default.

388
.. ghc-flag:: -Wdeprecations
389
390
391
392
393
    :shortdesc: warn about uses of functions & types that have warnings or
        deprecated pragmas. Alias for :ghc-flag:`-Wwarnings-deprecations`
    :type: dynamic
    :reverse: -Wno-deprecations
    :category:
394
395
396
397
398
399
400
401
402
403
404

    .. index::
       single: deprecations

    Causes a warning to be emitted when a module, function or type with
    a ``WARNING`` or ``DEPRECATED pragma`` is used. See
    :ref:`warning-deprecated-pragma` for more details on the pragmas.
    An alias for :ghc-flag:`-Wwarnings-deprecations`.

    This option is on by default.

405
.. ghc-flag:: -Wamp
406
407
408
409
410
    :shortdesc: *(deprecated)* warn on definitions conflicting with the
        Applicative-Monad Proposal (AMP)
    :type: dynamic
    :reverse: -Wno-amp
    :category:
411

412
413
414
415
    .. index::
       single: AMP
       single: Applicative-Monad Proposal

quchen's avatar
quchen committed
416
    This option is deprecated.
417

quchen's avatar
quchen committed
418
419
420
    Caused a warning to be emitted when a definition was in conflict with
    the AMP (Applicative-Monad proosal).

421
.. ghc-flag:: -Wnoncanonical-monad-instances
422
423
424
425
426
427
428
    :shortdesc: warn when ``Applicative`` or ``Monad`` instances have
        noncanonical definitions of ``return``, ``pure``, ``(>>)``,
        or ``(*>)``.
        See flag description in :ref:`options-sanity` for more details.
    :type: dynamic
    :reverse: -Wno-noncanonical-monad-instances
    :category:
429
430
431
432
433
434
435
436
437
438
439
440

    Warn if noncanonical ``Applicative`` or ``Monad`` instances
    declarations are detected.

    When this warning is enabled, the following conditions are verified:

    In ``Monad`` instances declarations warn if any of the following
    conditions does not hold:

     * If ``return`` is defined it must be canonical (i.e. ``return = pure``).
     * If ``(>>)`` is defined it must be canonical (i.e. ``(>>) = (*>)``).

441
    Moreover, in ``Applicative`` instance declarations:
442
443
444
445
446
447

     * Warn if ``pure`` is defined backwards (i.e. ``pure = return``).
     * Warn if ``(*>)`` is defined backwards (i.e. ``(*>) = (>>)``).

    This option is off by default.

448
.. ghc-flag:: -Wnoncanonical-monadfail-instances
449
450
451
452
453
454
    :shortdesc: warn when ``Monad`` or ``MonadFail`` instances have
        noncanonical definitions of ``fail``.
        See flag description in :ref:`options-sanity` for more details.
    :type: dynamic
    :reverse: -Wno-noncanonical-monadfail-instances
    :category:
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471

    Warn if noncanonical ``Monad`` or ``MonadFail`` instances
    declarations are detected.

    When this warning is enabled, the following conditions are verified:

    In ``Monad`` instances declarations warn if any of the following
    conditions does not hold:

     * If ``fail`` is defined it must be canonical
       (i.e. ``fail = Control.Monad.Fail.fail``).

    Moreover, in ``MonadFail`` instance declarations:

     * Warn if ``fail`` is defined backwards
       (i.e. ``fail = Control.Monad.fail``).

472
    See also :ghc-flag:`-Wmissing-monadfail-instances`.
473
474
475

    This option is off by default.

476
.. ghc-flag:: -Wnoncanonical-monoid-instances
477
478
479
480
481
482
    :shortdesc: warn when ``Semigroup`` or ``Monoid`` instances have
        noncanonical definitions of ``(<>)`` or ``mappend``.
        See flag description in :ref:`options-sanity` for more details.
    :type: dynamic
    :reverse: -Wno-noncanonical-monoid-instances
    :category:
483
484
485
486
487
488
489
490
491
492
493
494

    Warn if noncanonical ``Semigroup`` or ``Monoid`` instances
    declarations are detected.

    When this warning is enabled, the following conditions are verified:

    In ``Monoid`` instances declarations warn if any of the following
    conditions does not hold:

     * If ``mappend`` is defined it must be canonical
       (i.e. ``mappend = (Data.Semigroup.<>)``).

495
    Moreover, in ``Semigroup`` instance declarations:
496
497
498
499

     * Warn if ``(<>)`` is defined backwards (i.e. ``(<>) = mappend``).

    This warning is off by default. However, it is part of the
500
501
    :ghc-flag:`-Wcompat` option group.

502
.. ghc-flag:: -Wmissing-monadfail-instances
503
504
505
506
507
    :shortdesc: Warn when a failable pattern is used in a do-block that does
        not have a ``MonadFail`` instance.
    :type: dynamic
    :reverse: -Wno-missing-monadfail-instances
    :category:
508

quchen's avatar
quchen committed
509
510
511
512
513
514
515
    .. index::
       single: MFP
       single: MonadFail Proposal

    Warn when a failable pattern is used in a do-block that does not have a
    ``MonadFail`` instance.

516
517
    See also :ghc-flag:`-Wnoncanonical-monadfail-instances`.

518
    Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
quchen's avatar
quchen committed
519
    default, but will be switched on in a future GHC release, as part of
520
521
    the `MonadFail Proposal (MFP)
    <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
522

523
.. ghc-flag:: -Wsemigroup
524
525
526
527
528
    :shortdesc: warn when a ``Monoid`` is not ``Semigroup``, and on non-
        ``Semigroup`` definitions of ``(<>)``?
    :type: dynamic
    :reverse: -Wno-semigroup
    :category:
529

530
    .. index::
531
       single: semigroup; warning
532
533
534
535

    Warn when definitions are in conflict with the future inclusion of
    ``Semigroup`` into the standard typeclasses.

536
537
538
     1. Instances of ``Monoid`` should also be instances of ``Semigroup``
     2. The ``Semigroup`` operator ``(<>)`` will be in ``Prelude``, which
        clashes with custom local definitions of such an operator
539

540
    Being part of the :ghc-flag:`-Wcompat` option group, this warning is off by
541
542
    default, but will be switched on in a future GHC release.

543
.. ghc-flag:: -Wdeprecated-flags
544
545
546
547
    :shortdesc: warn about uses of commandline flags that are deprecated
    :type: dynamic
    :reverse: -Wno-deprecated-flags
    :category:
548

549
    .. index::
550
       single: deprecated flags
551
552
553
554
555
556

    Causes a warning to be emitted when a deprecated command-line flag
    is used.

    This option is on by default.

557
.. ghc-flag:: -Wunsupported-calling-conventions
558
559
560
561
    :shortdesc: warn about use of an unsupported calling convention
    :type: dynamic
    :reverse: -Wno-unsupported-calling-conventions
    :category:
562
563
564
565
566
567

    Causes a warning to be emitted for foreign declarations that use
    unsupported calling conventions. In particular, if the ``stdcall``
    calling convention is used on an architecture other than i386 then
    it will be treated as ``ccall``.

568
.. ghc-flag:: -Wdodgy-foreign-imports
569
570
571
572
    :shortdesc: warn about dodgy foreign imports
    :type: dynamic
    :reverse: -Wno-dodgy-foreign-import
    :category:
573
574

    Causes a warning to be emitted for foreign imports of the following
575
    form: ::
576
577
578

        foreign import "f" f :: FunPtr t

579
    on the grounds that it probably should be ::
580
581
582

        foreign import "&f" f :: FunPtr t

Ben Gamari's avatar
Ben Gamari committed
583
584
585
586
    The first form declares that ``f`` is a (pure) C function that takes
    no arguments and returns a pointer to a C function with type ``t``,
    whereas the second form declares that ``f`` itself is a C function
    with type ``t``. The first declaration is usually a mistake, and one
587
588
589
    that is hard to debug because it results in a crash, hence this
    warning.

590
.. ghc-flag:: -Wdodgy-exports
591
592
593
594
    :shortdesc: warn about dodgy exports
    :type: dynamic
    :reverse: -Wno-dodgy-exports
    :category:
595
596
597
598
599
600
601
602

    Causes a warning to be emitted when a datatype ``T`` is exported
    with all constructors, i.e. ``T(..)``, but is it just a type
    synonym.

    Also causes a warning to be emitted when a module is re-exported,
    but that module exports nothing.

603
.. ghc-flag:: -Wdodgy-imports
604
605
606
607
    :shortdesc: warn about dodgy imports
    :type: dynamic
    :reverse: -Wno-dodgy-imports
    :category:
608
609
610
611
612
613
614
615
616

    Causes a warning to be emitted in the following cases:

    -  When a datatype ``T`` is imported with all constructors, i.e.
       ``T(..)``, but has been exported abstractly, i.e. ``T``.

    -  When an ``import`` statement hides an entity that is not
       exported.

617
.. ghc-flag:: -Woverflowed-literals
618
619
620
621
    :shortdesc: warn about literals that will overflow their type
    :type: dynamic
    :reverse: -Wno-overflowed-literals
    :category:
622
623
624
625

    Causes a warning to be emitted if a literal will overflow, e.g.
    ``300 :: Word8``.

626
.. ghc-flag:: -Wempty-enumerations
627
628
629
630
    :shortdesc: warn about enumerations that are empty
    :type: dynamic
    :reverse: -Wno-empty-enumerations
    :category:
631
632
633
634

    Causes a warning to be emitted if an enumeration is empty, e.g.
    ``[5 .. 3]``.

635
.. ghc-flag:: -Wduplicate-constraints
636
637
638
639
    :shortdesc: warn when a constraint appears duplicated in a type signature
    :type: dynamic
    :reverse: -Wno-duplicate-constraints
    :category:
640

641
642
643
644
    .. index::
       single: duplicate constraints, warning

    Have the compiler warn about duplicate constraints in a type
645
    signature. For example ::
646
647
648
649
650
651

        f :: (Eq a, Show a, Eq a) => a -> a

    The warning will indicate the duplicated ``Eq a`` constraint.

    This option is now deprecated in favour of
652
653
654
    :ghc-flag:`-Wredundant-constraints`.

.. ghc-flag:: -Wredundant-constraints
655
656
657
658
659
    :shortdesc: Have the compiler warn about redundant constraints in type
        signatures.
    :type: dynamic
    :reverse: -Wno-redundant-constraints
    :category:
660

661
662
    :since: 8.0

663
664
665
666
667
668
    .. index::
       single: redundant constraints, warning

    Have the compiler warn about redundant constraints in a type
    signature. In particular:

669
    -  A redundant constraint within the type signature itself: ::
670
671
672
673
674
675
676

            f :: (Eq a, Ord a) => a -> a

       The warning will indicate the redundant ``Eq a`` constraint: it
       is subsumed by the ``Ord a`` constraint.

    -  A constraint in the type signature is not used in the code it
677
       covers: ::
678
679
680
681
682
683
684
685
686
687
688

            f :: Eq a => a -> a -> Bool
            f x y = True

       The warning will indicate the redundant ``Eq a`` constraint: : it
       is not used by the definition of ``f``.)

    Similar warnings are given for a redundant constraint in an instance
    declaration.

    This option is on by default. As usual you can suppress it on a
Ben Gamari's avatar
Ben Gamari committed
689
    per-module basis with :ghc-flag:`-Wno-redundant-constraints <-Wredundant-constraints>`.
690
691
692
693
    Occasionally you may specifically want a function to have a more
    constrained signature than necessary, perhaps to leave yourself
    wiggle-room for changing the implementation without changing the
    API. In that case, you can suppress the warning on a per-function
694
    basis, using a call in a dead binding. For example: ::
695
696
697
698
699
700
701
702
703

        f :: Eq a => a -> a -> Bool
        f x y = True
        where
            _ = x == x  -- Suppress the redundant-constraint warning for (Eq a)

    Here the call to ``(==)`` makes GHC think that the ``(Eq a)``
    constraint is needed, so no warning is issued.

704
.. ghc-flag:: -Wduplicate-exports
705
706
707
708
    :shortdesc: warn when an entity is exported multiple times
    :type: dynamic
    :reverse: -Wno-duplicate-exports
    :category:
709

710
711
712
713
714
715
716
717
718
719
720
    .. index::
       single: duplicate exports, warning
       single: export lists, duplicates

    Have the compiler warn about duplicate entries in export lists. This
    is useful information if you maintain large export lists, and want
    to avoid the continued export of a definition after you've deleted
    (one) mention of it in the export list.

    This option is on by default.

721
.. ghc-flag:: -Whi-shadowing
722
723
724
725
    :shortdesc: warn when a ``.hi`` file in the current directory shadows a library
    :type: dynamic
    :reverse: -Wno-hi-shadowing
    :category:
726

727
728
729
730
731
732
733
    .. index::
       single: shadowing; interface files

    Causes the compiler to emit a warning when a module or interface
    file in the current directory is shadowing one with the same module
    name in a library or other directory.

734
.. ghc-flag:: -Widentities
735
736
737
738
739
    :shortdesc: warn about uses of Prelude numeric conversions that are probably
        the identity (and hence could be omitted)
    :type: dynamic
    :reverse: -Wno-identities
    :category:
740
741

    Causes the compiler to emit a warning when a Prelude numeric
742
    conversion converts a type ``T`` to the same type ``T``; such calls are
743
744
745
    probably no-ops and can be omitted. The functions checked for are:
    ``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.

746
.. ghc-flag:: -Wimplicit-prelude
747
748
749
750
    :shortdesc: warn when the Prelude is implicitly imported
    :type: dynamic
    :reverse: -Wno-implicit-prelude
    :category:
751

752
753
754
    .. index::
       single: implicit prelude, warning

755
756
757
758
759
    Have the compiler warn if the Prelude is implicitly imported. This happens
    unless either the Prelude module is explicitly imported with an ``import
    ... Prelude ...`` line, or this implicit import is disabled (either by
    :ghc-flag:`-XNoImplicitPrelude` or a ``LANGUAGE NoImplicitPrelude``
    pragma).
760

761
762
763
764
765
766
    Note that no warning is given for syntax that implicitly refers to the
    Prelude, even if :ghc-flag:`-XNoImplicitPrelude` would change whether it
    refers to the Prelude. For example, no warning is given when ``368`` means
    ``Prelude.fromInteger (368::Prelude.Integer)`` (where ``Prelude`` refers
    to the actual Prelude module, regardless of the imports of the module
    being compiled).
767
768
769

    This warning is off by default.

770
.. ghc-flag:: -Wincomplete-patterns
771
772
773
774
    :shortdesc: warn when a pattern match could fail
    :type: dynamic
    :reverse: -Wno-incomplete-patterns
    :category:
775

776
777
778
779
    .. index::
       single: incomplete patterns, warning
       single: patterns, incomplete

780
    The option :ghc-flag:`-Wincomplete-patterns` warns about places where a
781
782
    pattern-match might fail at runtime. The function ``g`` below will
    fail when applied to non-empty lists, so the compiler will emit a
783
    warning about this when :ghc-flag:`-Wincomplete-patterns` is enabled. ::
784
785
786
787
788
789

        g [] = 2

    This option isn't enabled by default because it can be a bit noisy,
    and it doesn't always indicate a bug in the program. However, it's
    generally considered good practice to cover all the cases in your
790
    functions, and it is switched on by :ghc-flag:`-W`.
791

792
793
794
795
796
797
798
799
800
801
802
803

.. ghc-flag:: -Wincomplete-uni-patterns
    :shortdesc: warn when a pattern match in a lambda expression or
        pattern binding could fail
    :type: dynamic
    :reverse: -Wno-incomplete-uni-patterns
    :category:

    The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar to
    :ghc-flag:`-Wincomplete-patterns`, except that it applies only to
    lambda-expressions and pattern bindings, constructs that only allow a
    single pattern: ::
804
805
806
807

        h = \[] -> 2
        Just k = f y

808
.. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩
809
810
811
    :shortdesc: the iteration limit for the pattern match checker
    :type: dynamic
    :category:
812
813
814
815
816
817
818
819
820
821
822

    :default: 2000000

    Sets how many iterations of the pattern-match checker will perform before
    giving up. This limit is to catch cases where pattern-match checking might
    be excessively costly (due to the exponential complexity of coverage
    checking in the general case). It typically shouldn't be necessary to set
    this unless GHC informs you that it has exceeded the pattern match checker's
    iteration limit (in which case you may want to consider refactoring your
    pattern match, for the sake of future readers of your code.

823
.. ghc-flag:: -Wincomplete-record-updates
824
825
826
827
    :shortdesc: warn when a record update could fail
    :type: dynamic
    :reverse: -Wno-incomplete-record-updates
    :category:
828

829
830
831
832
833
834
    .. index::
       single: incomplete record updates, warning
       single: record updates, incomplete

    The function ``f`` below will fail when applied to ``Bar``, so the
    compiler will emit a warning about this when
835
    :ghc-flag:`-Wincomplete-record-updates` is enabled. ::
836
837
838
839
840
841
842
843
844
845

        data Foo = Foo { x :: Int }
                 | Bar

        f :: Foo -> Foo
        f foo = foo { x = 6 }

    This option isn't enabled by default because it can be very noisy,
    and it often doesn't indicate a bug in the program.

846
.. ghc-flag:: -Wmissing-fields
847
848
849
850
    :shortdesc: warn when fields of a record are uninitialised
    :type: dynamic
    :reverse: -Wno-missing-fields
    :category:
851

852
853
854
855
856
857
858
859
860
861
    .. index::
       single: missing fields, warning
       single: fields, missing

    This option is on by default, and warns you whenever the
    construction of a labelled field constructor isn't complete, missing
    initialisers for one or more fields. While not an error (the missing
    fields are initialised with bottoms), it is often an indication of a
    programmer error.

862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
.. ghc-flag:: -Wmissing-export-lists
    :shortdesc: warn when a module declaration does not explicitly list all
        exports
    :type: dynamic
    :reverse: -fnowarn-missing-export-lists
    :category:

    :since: 8.4.1

    .. index::
       single: missing export lists, warning
       single: export lists, missing

    This flag warns if you declare a module without declaring an explicit
    export list. For example ::

        module M where

          p x = x

    The :ghc-flag:`-Wmissing-export-lists` flag will warn that ``M`` does not
    declare an export list. Declaring an explicit export list for ``M`` enables
    GHC dead code analysis, prevents accidental export of names and can ease
    optimizations like inlining.

887
.. ghc-flag:: -Wmissing-import-lists
888
889
890
891
892
    :shortdesc: warn when an import declaration does not explicitly list all the
        names brought into scope
    :type: dynamic
    :reverse: -fnowarn-missing-import-lists
    :category:
893

894
895
896
897
898
899
    .. index::
       single: missing import lists, warning
       single: import lists, missing

    This flag warns if you use an unqualified ``import`` declaration
    that does not explicitly list the entities brought into scope. For
900
    example ::
901
902
903
904
905
906
907

        module M where
          import X( f )
          import Y
          import qualified Z
          p x = f x x

908
909
910
911
912
913
914
    The :ghc-flag:`-Wmissing-import-lists` flag will warn about the import of
    ``Y`` but not ``X`` If module ``Y`` is later changed to export (say) ``f``,
    then the reference to ``f`` in ``M`` will become ambiguous. No warning is
    produced for the import of ``Z`` because extending ``Z``\'s exports would be
    unlikely to produce ambiguity in ``M``.

.. ghc-flag:: -Wmissing-methods
915
916
917
918
    :shortdesc: warn when class methods are undefined
    :type: dynamic
    :reverse: -Wno-missing-methods
    :category:
919
920
921
922
923
924
925
926
927
928
929
930
931

    .. index::
       single: missing methods, warning
       single: methods, missing

    This option is on by default, and warns you whenever an instance
    declaration is missing one or more methods, and the corresponding
    class declaration has no default declaration for them.

    The ``MINIMAL`` pragma can be used to change which combination of
    methods will be required for instances of a particular class. See
    :ref:`minimal-pragma`.

932
.. ghc-flag:: -Wmissing-signatures
933
934
935
936
    :shortdesc: warn about top-level functions without signatures
    :type: dynamic
    :reverse: -Wno-missing-signatures
    :category:
937

938
939
940
941
    .. index::
       single: type signatures, missing

    If you would like GHC to check that every top-level function/value
942
    has a type signature, use the :ghc-flag:`-Wmissing-signatures` option.
943
944
945
    As part of the warning GHC also reports the inferred type. The
    option is off by default.

946
.. ghc-flag:: -Wmissing-exported-sigs
947
948
949
950
951
952
    :shortdesc: *(deprecated)*
        warn about top-level functions without signatures, only if they
        are exported. takes precedence over -Wmissing-signatures
    :type: dynamic
    :reverse: -Wno-missing-exported-sigs
    :category:
953

manav's avatar
manav committed
954
955
956
957
958
959
960
    .. index::
       single: type signatures, missing

    This option is now deprecated in favour of
    :ghc-flag:`-Wmissing-exported-signatures`.

.. ghc-flag:: -Wmissing-exported-signatures
961
962
963
964
965
    :shortdesc: warn about top-level functions without signatures, only if they
        are exported. takes precedence over -Wmissing-signatures
    :type: dynamic
    :reverse: -Wno-missing-exported-signatures
    :category:
manav's avatar
manav committed
966

967
968
969
970
971
    .. index::
       single: type signatures, missing

    If you would like GHC to check that every exported top-level
    function/value has a type signature, but not check unexported
manav's avatar
manav committed
972
973
974
975
    values, use the :ghc-flag:`-Wmissing-exported-signatures`
    option. This option takes precedence over
    :ghc-flag:`-Wmissing-signatures`. As part of the warning GHC also
    reports the inferred type. The option is off by default.
976

977
.. ghc-flag:: -Wmissing-local-sigs
978
979
980
981
982
    :shortdesc: *(deprecated)*
        warn about polymorphic local bindings without signatures
    :type: dynamic
    :reverse: -Wno-missing-local-sigs
    :category:
983

984
985
986
    .. index::
       single: type signatures, missing

manav's avatar
manav committed
987
988
989
990
    This option is now deprecated in favour of
    :ghc-flag:`-Wmissing-local-signatures`.

.. ghc-flag:: -Wmissing-local-signatures
991
992
993
994
    :shortdesc: warn about polymorphic local bindings without signatures
    :type: dynamic
    :reverse: -Wno-missing-local-signatures
    :category:
manav's avatar
manav committed
995
996
997
998
999
1000
1001
1002

    .. index::
       single: type signatures, missing

    If you use the :ghc-flag:`-Wmissing-local-signatures` flag GHC
    will warn you about any polymorphic local bindings. As part of the
    warning GHC also reports the inferred type. The option is off by
    default.
1003

manav's avatar
manav committed
1004
.. ghc-flag:: -Wmissing-pattern-synonym-signatures
1005
1006
1007
1008
    :shortdesc: warn when pattern synonyms do not have type signatures
    :type: dynamic
    :reverse: -Wno-missing-pattern-synonym-signatures
    :category:
1009
1010
1011
1012

    .. index::
         single: type signatures, missing, pattern synonyms

manav's avatar
manav committed
1013
1014
1015
1016
1017
1018
1019
    If you would like GHC to check that every pattern synonym has a
    type signature, use the
    :ghc-flag:`-Wmissing-pattern-synonym-signatures` option. If this
    option is used in conjunction with
    :ghc-flag:`-Wmissing-exported-signatures` then only exported pattern
    synonyms must have a type signature. GHC also reports the inferred
    type. This option is off by default.
1020

1021
.. ghc-flag:: -Wname-shadowing
1022
1023
1024
1025
    :shortdesc: warn when names are shadowed
    :type: dynamic
    :reverse: -Wno-name-shadowing
    :category:
1026

1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
    .. index::
       single: shadowing, warning

    This option causes a warning to be emitted whenever an inner-scope
    value has the same name as an outer-scope value, i.e. the inner
    value shadows the outer one. This can catch typographical errors
    that turn into hard-to-find bugs, e.g., in the inadvertent capture
    of what would be a recursive call in
    ``f = ... let f = id in ... f ...``.

    The warning is suppressed for names beginning with an underscore.
1038
    For example ::
1039
1040
1041

        f x = do { _ignore <- this; _ignore <- that; return (the other) }

1042
.. ghc-flag:: -Worphans
1043
1044
1045
1046
1047
    :shortdesc: warn when the module contains :ref:`orphan instance declarations
        or rewrite rules <orphan-modules>`
    :type: dynamic
    :reverse: -Wno-orphans
    :category:
1048

1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
    .. index::
       single: orphan instances, warning
       single: orphan rules, warning

    These flags cause a warning to be emitted whenever the module
    contains an "orphan" instance declaration or rewrite rule. An
    instance declaration is an orphan if it appears in a module in which
    neither the class nor the type being instanced are declared in the
    same module. A rule is an orphan if it is a rule for a function
    declared in another module. A module containing any orphans is
    called an orphan module.

    The trouble with orphans is that GHC must pro-actively read the
    interface files for all orphan modules, just in case their instances
    or rules play a role, whether or not the module's interface would
    otherwise be of any use. See :ref:`orphan-modules` for details.

1066
    The flag :ghc-flag:`-Worphans` warns about user-written orphan rules or
1067
    instances.
1068

1069
.. ghc-flag:: -Woverlapping-patterns
1070
1071
1072
1073
    :shortdesc: warn about overlapping patterns
    :type: dynamic
    :reverse: -Wno-overlapping-patterns
    :category:
1074

1075
1076
1077
1078
1079
    .. index::
       single: overlapping patterns, warning
       single: patterns, overlapping

    By default, the compiler will warn you if a set of patterns are
1080
    overlapping, e.g., ::
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090

        f :: String -> Int
        f []     = 0
        f (_:xs) = 1
        f "2"    = 2

    where the last pattern match in ``f`` won't ever be reached, as the
    second pattern overlaps it. More often than not, redundant patterns
    is a programmer mistake/error, so this option is enabled by default.

1091
.. ghc-flag:: -Wsimplifiable-class-constraints
1092
1093
1094
1095
1096
    :shortdesc: 2arn about class constraints in a type signature that can
        be simplified using a top-level instance declaration.
    :type: dynamic
    :reverse: -Wno-overlapping-patterns
    :category:
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115

    :since: 8.2

    .. index::
       single: simplifiable class constraints, warning

    Warn about class constraints in a type signature that can be simplified
    using a top-level instance declaration.  For example: ::

       f :: Eq [a] => a -> a

    Here the ``Eq [a]`` in the signature overlaps with the top-level
    instance for ``Eq [a]``.  GHC goes to some efforts to use the former,
    but if it should use the latter, it would then have an
    insoluble ``Eq a`` constraint.  Best avoided by instead writing: ::

       f :: Eq a => a -> a

    This option is on by default. As usual you can suppress it on a
Ben Gamari's avatar
Ben Gamari committed
1116
1117
    per-module basis with :ghc-flag:`-Wno-simplifiable-class-constraints
    <-Wsimplifiable-class-constraints>`.
1118

1119
.. ghc-flag:: -Wtabs
1120
1121
1122
1123
    :shortdesc: warn if there are tabs in the source file
    :type: dynamic
    :reverse: -Wno-tabs
    :category:
1124

1125
1126
1127
1128
1129
    .. index::
       single: tabs, warning

    Have the compiler warn if there are tabs in your source file.

1130
.. ghc-flag:: -Wtype-defaults
1131
1132
1133
1134
    :shortdesc: warn when defaulting happens
    :type: dynamic
    :reverse: -Wno-type-defaults
    :category:
1135

1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
    .. index::
       single: defaulting mechanism, warning

    Have the compiler warn/inform you where in your source the Haskell
    defaulting mechanism for numeric types kicks in. This is useful
    information when converting code from a context that assumed one
    default into one with another, e.g., the ‘default default’ for
    Haskell 1.4 caused the otherwise unconstrained value ``1`` to be
    given the type ``Int``, whereas Haskell 98 and later defaults it to
    ``Integer``. This may lead to differences in performance and
    behaviour, hence the usefulness of being non-silent about this.

    This warning is off by default.

1150
.. ghc-flag:: -Wmonomorphism-restriction
1151
1152
1153
1154
    :shortdesc: warn when the Monomorphism Restriction is applied
    :type: dynamic
    :reverse: -Wno-monomorphism-restriction
    :category:
1155

1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
    .. index::
       single: monomorphism restriction, warning

    Have the compiler warn/inform you where in your source the Haskell
    Monomorphism Restriction is applied. If applied silently the MR can
    give rise to unexpected behaviour, so it can be helpful to have an
    explicit warning that it is being applied.

    This warning is off by default.

1166
.. ghc-flag:: -Wunsupported-llvm-version
1167
1168
1169
1170
1171
    :shortdesc: Warn when using :ghc-flag:`-fllvm` with an unsupported
        version of LLVM.
    :type: dynamic
    :reverse: -Wno-monomorphism-restriction
    :category:
1172
1173
1174
1175

    Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.

.. ghc-flag:: -Wunticked-promoted-constructors
1176
1177
1178
1179
    :shortdesc: warn if promoted constructors are not ticked
    :type: dynamic
    :reverse: -Wno-unticked-promoted-constructors
    :category:
1180

1181
1182
1183
1184
1185
1186
    .. index::
       single: promoted constructor, warning

    Warn if a promoted data constructor is used without a tick preceding
    its name.

1187
    For example: ::
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197

        data Nat = Succ Nat | Zero

        data Vec n s where
          Nil  :: Vec Zero a
          Cons :: a -> Vec n a -> Vec (Succ n) a

    Will raise two warnings because ``Zero`` and ``Succ`` are not
    written as ``'Zero`` and ``'Succ``.

Gabor Greif's avatar
Gabor Greif committed
1198
    This warning is enabled by default in :ghc-flag:`-Wall` mode.
1199
1200

.. ghc-flag:: -Wunused-binds
1201
1202
1203
1204
1205
1206
    :shortdesc: warn about bindings that are unused. Alias for
        :ghc-flag:`-Wunused-top-binds`, :ghc-flag:`-Wunused-local-binds` and
        :ghc-flag:`-Wunused-pattern-binds`
    :type: dynamic
    :reverse: -Wno-unused-binds
    :category:
1207
1208
1209
1210
1211
1212
1213
1214

    .. index::
       single: unused binds, warning
       single: binds, unused

    Report any function definitions (and local bindings) which are
    unused. An alias for

1215
1216
1217
1218
1219
    -  :ghc-flag:`-Wunused-top-binds`
    -  :ghc-flag:`-Wunused-local-binds`
    -  :ghc-flag:`-Wunused-pattern-binds`

.. ghc-flag:: -Wunused-top-binds
1220
1221
1222
1223
    :shortdesc: warn about top-level bindings that are unused
    :type: dynamic
    :reverse: -Wno-unused-top-binds
    :category:
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242

    .. index::
       single: unused binds, warning
       single: binds, unused

    Report any function definitions which are unused.

    More precisely, warn if a binding brings into scope a variable that
    is not used, except if the variable's name starts with an
    underscore. The "starts-with-underscore" condition provides a way to
    selectively disable the warning.

    A variable is regarded as "used" if

    -  It is exported, or

    -  It appears in the right hand side of a binding that binds at
       least one used variable that is used

1243
    For example: ::
1244
1245
1246
1247
1248
1249
1250
1251
1252

        module A (f) where
        f = let (p,q) = rhs1 in t p  -- No warning: q is unused, but is locally bound
        t = rhs3                     -- No warning: f is used, and hence so is t
        g = h x                      -- Warning: g unused
        h = rhs2                     -- Warning: h is only used in the
                                     -- right-hand side of another unused binding
        _w = True                    -- No warning: _w starts with an underscore

1253
.. ghc-flag:: -Wunused-local-binds
1254
1255
1256
1257
    :shortdesc: warn about local bindings that are unused
    :type: dynamic
    :reverse: -Wno-unused-local-binds
    :category:
1258

1259
1260
1261
1262
    .. index::
       single: unused binds, warning
       single: binds, unused

1263
    Report any local definitions which are unused. For example: ::
1264
1265
1266
1267
1268

        module A (f) where
        f = let (p,q) = rhs1 in t p  -- Warning: q is unused
        g = h x                      -- No warning: g is unused, but is a top-level binding

1269
.. ghc-flag:: -Wunused-pattern-binds
1270
1271
1272
1273
    :shortdesc: warn about pattern match bindings that are unused
    :type: dynamic
    :reverse: -Wno-unused-pattern-binds
    :category:
1274

1275
1276
1277
1278
1279
    .. index::
       single: unused binds, warning
       single: binds, unused

    Warn if a pattern binding binds no variables at all, unless it is a
1280
    lone wild-card pattern, or a banged pattern. For example: ::
1281
1282
1283
1284

        Just _ = rhs3    -- Warning: unused pattern binding
        (_, _) = rhs4    -- Warning: unused pattern binding
        _  = rhs3        -- No warning: lone wild-card pattern
1285
        !() = rhs4       -- No warning: banged pattern; behaves like seq
1286

1287
1288
    In general a lazy pattern binding `p = e` is a no-op if `p` does not
    bind any variables.
1289
1290
1291
    The motivation for allowing lone wild-card patterns is they are not
    very different from ``_v = rhs3``, which elicits no warning; and
    they can be useful to add a type constraint, e.g. ``_ = x::Int``. A
1292
1293
    banged pattern (see :ref:`bang-patterns`) is *not* a no-op, because
    it forces evaluation, and is useful as an alternative to ``seq``.
1294

1295
.. ghc-flag:: -Wunused-imports
1296
1297
1298
1299
    :shortdesc: warn about unnecessary imports
    :type: dynamic
    :reverse: -Wno-unused-imports
    :category:
1300

1301
1302
1303
1304
1305
1306
1307
1308
1309
    .. index::
       single: unused imports, warning
       single: imports, unused

    Report any modules that are explicitly imported but never used.
    However, the form ``import M()`` is never reported as an unused
    import, because it is a useful idiom for importing instance
    declarations, which are anonymous in Haskell.

1310
.. ghc-flag:: -Wunused-matches
1311
1312
1313
1314
    :shortdesc: warn about variables in patterns that aren't used
    :type: dynamic
    :reverse: -Wno-unused-matches
    :category:
1315

1316
1317
1318
1319
    .. index::
       single: unused matches, warning
       single: matches, unused

1320
1321
    Report all unused variables which arise from term-level pattern matches,
    including patterns consisting of a single variable. For instance
1322
    ``f x y = []`` would report ``x`` and ``y`` as unused. The warning
1323
    is suppressed if the variable name begins with an underscore, thus: ::
1324
1325
1326

        f _x = True

1327
1328
1329
1330
1331
    Note that :ghc-flag:`-Wunused-matches` does not warn about variables which
    arise from type-level patterns, as found in type family and data family
    instances. This must be enabled separately through the
    :ghc-flag:`-Wunused-type-patterns` flag.

1332
.. ghc-flag:: -Wunused-do-bind
1333
1334
1335
1336
1337
    :shortdesc: warn about do bindings that appear to throw away values of types
        other than ``()``
    :type: dynamic
    :reverse: -Wno-unused-do-bind
    :category:
1338

1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
    .. index::
       single: unused do binding, warning
       single: do binding, unused

    Report expressions occurring in ``do`` and ``mdo`` blocks that
    appear to silently throw information away. For instance
    ``do { mapM popInt xs ; return 10 }`` would report the first
    statement in the ``do`` block as suspicious, as it has the type
    ``StackM [Int]`` and not ``StackM ()``, but that ``[Int]`` value is
    not bound to anything. The warning is suppressed by explicitly
    mentioning in the source code that your program is throwing
1350
    something away: ::
1351
1352
1353

        do { _ <- mapM popInt xs ; return 10 }

1354
    Of course, in this particular situation you can do even better: ::
1355
1356
1357

        do { mapM_ popInt xs ; return 10 }

1358
.. ghc-flag:: -Wunused-type-patterns
1359
1360
1361
1362
1363
    :shortdesc: warn about unused type variables which arise from patterns
        in type family and data family instances
    :type: dynamic
    :reverse: -Wno-unused-type-patterns
    :category:
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378

    .. index::
       single: unused type patterns, warning
       single: type patterns, unused

    Report all unused type variables which arise from patterns in type family
    and data family instances. For instance: ::

        type instance F x y = []

    would report ``x`` and ``y`` as unused. The warning is suppressed if the
    type variable name begins with an underscore, like so: ::

        type instance F _x _y = []

Ben Gamari's avatar
Ben Gamari committed
1379
    Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-patterns` is
1380
1381
1382
1383
1384
1385
    not implied by :ghc-flag:`-Wall`. The rationale for this decision is that
    unlike term-level pattern names, type names are often chosen expressly for
    documentation purposes, so using underscores in type names can make the
    documentation harder to read.

.. ghc-flag:: -Wunused-foralls
1386
1387
1388
1389
1390
    :shortdesc: warn about type variables in user-written
        ``forall``\\s that are unused
    :type: dynamic
    :reverse: -Wno-unused-foralls
    :category:
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402

    .. index::
       single: unused foralls, warning
       single: foralls, unused

    Report all unused type variables which arise from explicit, user-written
    ``forall`` statements. For instance: ::

        g :: forall a b c. (b -> b)

    would report ``a`` and ``c`` as unused.

1403
.. ghc-flag:: -Wwrong-do-bind
1404
1405
1406
1407
1408
    :shortdesc: warn about do bindings that appear to throw away monadic values
        that you should have bound instead
    :type: dynamic
    :reverse: -Wno-wrong-do-bind
    :category:
1409

1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
    .. index::
       single: apparently erroneous do binding, warning
       single: do binding, apparently erroneous

    Report expressions occurring in ``do`` and ``mdo`` blocks that
    appear to lack a binding. For instance
    ``do { return (popInt 10) ; return 10 }`` would report the first
    statement in the ``do`` block as suspicious, as it has the type
    ``StackM (StackM Int)`` (which consists of two nested applications
    of the same monad constructor), but which is not then "unpacked" by
    binding the result. The warning is suppressed by explicitly
    mentioning in the source code that your program is throwing
1422
    something away: ::
1423
1424
1425
1426

        do { _ <- return (popInt 10) ; return 10 }

    For almost all sensible programs this will indicate a bug, and you
1427
    probably intended to write: ::
1428
1429
1430

        do { popInt 10 ; return 10 }

1431
.. ghc-flag:: -Winline-rule-shadowing
1432
1433
1434
1435
1436
1437
    :shortdesc: Warn if a rewrite RULE might fail to fire because the
        function might be inlined before the rule has a chance to fire.
        See :ref:`rules-inline`.
    :type: dynamic
    :reverse: -Wno-inline-rule-shadowing
    :category:
1438
1439
1440
1441
1442

    Warn if a rewrite RULE might fail to fire because the function might
    be inlined before the rule has a chance to fire. See
    :ref:`rules-inline`.

1443
.. ghc-flag:: -Wcpp-undef
1444
1445
1446
    :shortdesc: warn on uses of the `#if` directive on undefined identifiers
    :type: dynamic
    :category:
1447

1448
1449
    :since: 8.2

1450
1451
1452
1453
    This flag passes ``-Wundef`` to the C pre-processor (if its being used)
    which causes the pre-processor to warn on uses of the `#if` directive on
    undefined identifiers.

Richard Eisenberg's avatar
Richard Eisenberg committed
1454
.. ghc-flag:: -Wunbanged-strict-patterns
1455
1456
1457
1458
1459
    :shortdesc: warn on pattern bind of unlifted variable that is neither bare
        nor banged
    :type: dynamic
    :reverse: -Wno-unbanged-strict-patterns
    :category:
Richard Eisenberg's avatar
Richard Eisenberg committed
1460
1461
1462

    This flag warns whenever you write a pattern that binds a variable whose
    type is unlifted, and yet the pattern is not a bang pattern nor a bare variable.
Yuras's avatar
Yuras committed
1463
1464