Commit eaeb28a1 authored by Ben Gamari's avatar Ben Gamari 🐢 Committed by Marge Bot
Browse files

users-guide: Fix various warnings

parent e9813afc
......@@ -147,7 +147,7 @@ Compiler
- Add new flag :ghc-flag:`-fkeep-going` which makes the compiler
continue as far as it can despite errors.
- Deprecated flag :ghc-flag:`-fwarn-hi-shadowing` because it was not
- Deprecated flag ``-fwarn-hi-shadowing`` because it was not
implemented correctly, and appears to be largely unused. This flag
will be removed in a later version of GHC.
......
......@@ -143,7 +143,7 @@ Compiler
~~~~~~~~
- GHC now no longer adds the current file's directory as a general include path
calling the C compiler. Instead we use :ghc-flag:`-iquote` to only add it as
calling the C compiler. Instead we use ``-iquote`` to only add it as
an include path for `#include ""`. See :ghc-ticket:`14312`.
- GHC now supports British spelling of :extension:`GeneralizedNewtypeDeriving`.
......
......@@ -138,7 +138,7 @@ Runtime system
See :ghc-ticket:`13617`. Note that committed memory may be slightly higher.
- The output filename used for :ref:`eventlog output <rts-eventlog>` can now be
specified with the :rts-flag:`-ol` flag.
specified with the :rts-flag:`-ol ⟨filename⟩` flag.
- Add support for generating a new type of output: extended interfaces files.
Generation of these files, which sport a ``.hie`` suffix, is enabled via the
......
......@@ -424,9 +424,10 @@ reliably re-initialise after this has happened; see :ref:`infelicities-ffi`.
To use ``+RTS`` flags with ``hs_init()``, we have to modify the example
slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags (see
:ref:`options-linker`), and the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
link-time flag overrides this. However, :ghc-flag:`-rtsopts[=⟨none|some|all⟩]`
has no effect when :ghc-flag:`-no-hs-main` is in use (and the same goes for
:ref:`options-linker`), and the :ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]`
link-time flag overrides this. However,
:ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]` has no effect when
:ghc-flag:`-no-hs-main` is in use (and the same goes for
:ghc-flag:`-with-rtsopts=⟨opts⟩`). To set these options we have to call a
GHC-specific API instead of ``hs_init()``:
......
......@@ -1434,9 +1434,14 @@ triggered (see :ref:`nested-breakpoints`). Rather than forcing thunks,
:ghci-cmd:`:print` binds each thunk to a fresh variable beginning with an
underscore, in this case ``_t1``.
The flag :ghc-flag:`-fprint-evld-with-show` instructs :ghci-cmd:`:print` to reuse
available ``Show`` instances when possible. This happens only when the
contents of the variable being inspected are completely evaluated.
.. ghc-flag:: -fprint-evld-with-show
:shortdesc: Instruct :ghci-cmd:`:print` to use ``Show`` instances where possible.
:category: interactive
:type: dynamic
The flag :ghc-flag:`-fprint-evld-with-show` instructs :ghci-cmd:`:print` to reuse
available ``Show`` instances when possible. This happens only when the
contents of the variable being inspected are completely evaluated.
If we aren't concerned about preserving the evaluatedness of a variable, we can
use :ghci-cmd:`:force` instead of :ghci-cmd:`:print`. The :ghci-cmd:`:force`
......@@ -2572,7 +2577,7 @@ commonly used commands.
The command will match ⟨type⟩ with the first parameter of every
instance and then check that all constraints are satisfiable.
When combined with ``-XPartialTypeSignatures``, a user can insert
When combined with :extension:`PartialTypeSignatures`, a user can insert
wildcards into a query and learn the constraints required of each
wildcard for ⟨type⟩ match with an instance.
......@@ -3399,13 +3404,14 @@ providing it with a temporary folder (where it will copy the
necessary libraries to load to) and port it will listen for
the proxy to connect.
Providing :ghc-flag:`-pgmi /path/to/iserv-proxy`, :ghc-flag:`-pgmo ⟨option⟩`
and :ghc-flag:`-pgmo ⟨port⟩` in addition to :ghc-flag:`-fexternal-interpreter`
will then make ghc go through the proxy instead.
Providing :ghc-flag:`-pgmi /path/to/iserv-proxy <-pgmi ⟨cmd⟩>`,
:ghc-flag:`-pgmo ⟨option⟩` and :ghc-flag:`-pgmo ⟨port⟩` in addition to
:ghc-flag:`-fexternal-interpreter` will then make ghc go through the proxy
instead.
There are some limitations when using this. File and process IO
will be executed on the target. As such packages like git-embed,
file-embed and others might not behave as expected if the target
will be executed on the target. As such packages like ``git-embed``,
``file-embed`` and others might not behave as expected if the target
and host do not share the same filesystem.
.. _ghci-faq:
......
......@@ -2307,7 +2307,9 @@ Changes to the grammar
 
The Haskell report `defines
<https://www.haskell.org/onlinereport/haskell2010/haskellch3.html#x8-220003>`_
the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)::
the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)
.. code-block:: none
 
lexp → \ apat1 … apatn -> exp (lambda abstraction, n ≥ 1) *
| let decls in exp (let expression) *
......@@ -2327,7 +2329,9 @@ the ``lexp`` nonterminal thus (``*`` indicates a rule of interest)::
| …
 
The :extension:`BlockArguments` extension moves these production rules under
``aexp``::
``aexp``
.. code-block:: none
 
lexp → fexp
 
......@@ -3962,12 +3966,9 @@ GHC extends this mechanism along several axes:
Deriving instances for empty data types
---------------------------------------
 
.. ghc-flag:: -XEmptyDataDeriving
.. extension:: EmptyDataDeriving
:shortdesc: Allow deriving instances of standard type classes for
empty data types.
:type: dynamic
:reverse: -XNoEmptyDataDeriving
:category:
 
:since: 8.4.1
 
......@@ -4617,8 +4618,8 @@ Deriving ``Data`` instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
.. extension:: DeriveDataTypeable
:shortdesc: Enable deriving for the Data class.
Implied by (deprecated) :extension:`AutoDeriveTypeable`.
:shortdesc: Enable deriving for the ``Data`` class.
Implied by (deprecated) ``AutoDeriveTypeable``.
 
:since: 6.8.1
 
......@@ -10446,7 +10447,7 @@ The ``context =>`` part is optional. That is the only syntactic change to the l
 
Notes:
 
- Where GHC allows extensions instance declarations we allow exactly the same extensions to this new form of ``class``. Specifically, with :extension:`ExplicitForAll` and :extension:`MultiParameterTypeClasses` the syntax becomes
- Where GHC allows extensions instance declarations we allow exactly the same extensions to this new form of ``class``. Specifically, with :extension:`ExplicitForAll` and :extension:`MultiParamTypeClasses` the syntax becomes
 
.. code-block:: none
 
......@@ -11246,7 +11247,7 @@ assumptions", and a related `blog post
 
The extension :extension:`MonoLocalBinds` is implied by :extension:`TypeFamilies`
and :extension:`GADTs`. You can switch it off again with
:extension:`NoMonoLocalBinds <-XMonoLocalBinds>` but type inference becomes
:extension:`NoMonoLocalBinds <MonoLocalBinds>` but type inference becomes
less predictable if you do so. (Read the papers!)
 
.. _visible-type-application:
......@@ -11704,11 +11705,9 @@ monomorphic. This is important because by default GHC will not
instantiate type variables to a polymorphic type
(:ref:`impredicative-polymorphism`).
 
The obsolete language options :extension:`PolymorphicComponents` and
:extension:`Rank2Types` are synonyms for :extension:`RankNTypes`. They used to
specify finer distinctions that GHC no longer makes. (They should really elicit
a deprecation warning, but they don't, purely to avoid the need to library
authors to change their old flags specifications.)
The obsolete language option :extension:`Rank2Types` is a synonym for
:extension:`RankNTypes`. They used to specify finer distinctions that GHC no
longer makes.
 
.. _univ:
 
......@@ -12493,6 +12492,7 @@ Sorting can be toggled with :ghc-flag:`-fsort-valid-hole-fits`
:shortdesc: Disables the sorting of the list of valid hole fits for typed holes
in type error messages.
:type: dynamic
:reverse: -fsort-valid-hole-fits
:category: verbosity
 
:default: off
......@@ -12957,8 +12957,8 @@ Enabling deferring of type errors
 
The flag :ghc-flag:`-fdefer-type-errors` controls whether type errors are
deferred to runtime. Type errors will still be emitted as warnings, but
will not prevent compilation. You can use :ghc-flag:`-Wno-type-errors
<-Wtype-errors>` to suppress these warnings.
will not prevent compilation. You can use :ghc-flag:`-Wno-deferred-type-errors`
to suppress these warnings.
 
This flag implies the :ghc-flag:`-fdefer-typed-holes` and
:ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this behaviour
......@@ -15264,7 +15264,7 @@ used if you want your code to be portable).
Instructs GHC to consider a value to be especially cheap to inline.
 
An :pragma:`INLINE` or :pragma:`NOINLINE` pragma may have a :pragma:`CONLIKE` modifier, which affects
matching in :pragma:`RULE`\s (only). See :ref:`conlike`.
matching in :pragma:`RULE <RULES>`\s (only). See :ref:`conlike`.
 
.. _phase-control:
 
......@@ -15316,7 +15316,7 @@ arguments etc). Another way to understand the semantics is this:
body look small, so that when inlining is allowed it is very likely
to happen.
 
The same phase-numbering control is available for :pragma:`RULE`\s
The same phase-numbering control is available for :pragma:`RULE <RULES>`\s
(:ref:`rewrite-rules`).
 
.. _line-pragma:
......@@ -15521,9 +15521,9 @@ fire the first specialisation, whose body is also inlined. The result is
a type-based unrolling of the indexing function.
 
You can add explicit phase control (:ref:`phase-control`) to
``SPECIALISE INLINE`` pragma, just like on an :pragma:`INLINE` pragma; if you do
so, the same phase is used for the rewrite rule and the INLINE control of the
specialised function.
``SPECIALISE INLINE`` pragma, just like on an :pragma:`INLINE` pragma; if
you do so, the same phase is used for the rewrite rule and the INLINE control
of the specialised function.
 
.. warning:: You can make GHC diverge by using ``SPECIALISE INLINE`` on an
ordinarily-recursive function.
......@@ -15935,12 +15935,12 @@ From a syntactic point of view:
then C's rules are in force when compiling A.) The situation is very
similar to that for instance declarations.
 
- Inside a :pragma:`RULE` "``forall``" is treated as a keyword, regardless of any
other flag settings. Furthermore, inside a RULE, the language
- Inside a :pragma:`RULES` "``forall``" is treated as a keyword, regardless of any
other flag settings. Furthermore, inside a :pragma:`RULES`, the language
extension :extension:`ScopedTypeVariables` is automatically enabled; see
:ref:`scoped-type-variables`.
 
- Like other pragmas, :pragma:`RULE` pragmas are always checked for scope errors,
- Like other pragmas, :pragma:`RULES` pragmas are always checked for scope errors,
and are typechecked. Typechecking means that the LHS and RHS of a
rule are typechecked, and must have the same type. However, rules are
only *enabled* if the :ghc-flag:`-fenable-rewrite-rules` flag is on (see
......@@ -16029,13 +16029,13 @@ give ::
 
g y = y
 
Now ``g`` is inlined into ``h``, but ``f``\'s :pragma:`RULE` has no chance to
Now ``g`` is inlined into ``h``, but ``f``\'s RULE has no chance to
fire. If instead GHC had first inlined ``g`` into ``h`` then there would have
been a better chance that ``f``\'s :pragma:`RULE` might fire.
been a better chance that ``f``\'s :pragma:`RULES` might fire.
 
The way to get predictable behaviour is to use a :pragma:`NOINLINE` pragma, or an
INLINE[⟨phase⟩] pragma, on ``f``, to ensure that it is not inlined until
its RULEs have had a chance to fire. The warning flag
``INLINE[⟨phase⟩]`` pragma, on ``f``, to ensure that it is not inlined until
its :pragma:`RULES` have had a chance to fire. The warning flag
:ghc-flag:`-Winline-rule-shadowing` (see :ref:`options-sanity`) warns about
this situation.
 
......
......@@ -81,11 +81,11 @@ given compilation phase:
Use ⟨cmd⟩ as the DLL generator.
.. ghc-flag:: -pgmF ⟨cmd⟩
:shortdesc: Use ⟨cmd⟩ as the pre-processor (with ``-F`` only)
:shortdesc: Use ⟨cmd⟩ as the pre-processor (with :ghc-flag:`-F` only)
:type: dynamic
:category: phase-programs
Use ⟨cmd⟩ as the pre-processor (with ``-F`` only).
Use ⟨cmd⟩ as the pre-processor (with :ghc-flag:`-F` only).
.. ghc-flag:: -pgmwindres ⟨cmd⟩
:shortdesc: Use ⟨cmd⟩ as the program for embedding manifests on Windows.
......@@ -98,20 +98,20 @@ given compilation phase:
:ref:`options-linker`.
.. ghc-flag:: -pgmlibtool ⟨cmd⟩
:shortdesc: Use ⟨cmd⟩ as the command for libtool (with ``-staticlib`` only).
:shortdesc: Use ⟨cmd⟩ as the command for libtool (with :ghc-flag:`-staticlib` only).
:type: dynamic
:category: phase-programs
Use ⟨cmd⟩ as the libtool command (when using ``-staticlib`` only).
Use ⟨cmd⟩ as the libtool command (when using :ghc-flag:`-staticlib` only).
.. ghc-flag:: -pgmi ⟨cmd⟩
:shortdesc: Use ⟨cmd⟩ as the external interpreter command.
:type: dynamic
:category: phase-programs
Use ⟨cmd⟩ as the external interpreter command (see:
Use ⟨cmd⟩ as the external interpreter command (see
:ref:`external-interpreter`). Default: ``ghc-iserv-prof`` if
``-prof`` is enabled, ``ghc-iserv-dyn`` if ``-dynamic`` is
:ghc-flag:`-prof` is enabled, ``ghc-iserv-dyn`` if :ghc-flag:`-dynamic` is
enabled, or ``ghc-iserv`` otherwise.
.. _forcing-options-through:
......
......@@ -658,7 +658,7 @@ To generate a heap profile from your program:
:rts-flag:`-h` for a basic producer profile). This generates the file
:file:`{prog}.hp`.
If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l`
If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l ⟨flags⟩`
runtime system flag) heap samples will additionally be emitted to the GHC
event log (see :ref:`heap-profiler-events` for details about event format).
......
......@@ -50,9 +50,9 @@ Setting RTS options on the command line
single: -RTS
single: --RTS
If you set the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` flag appropriately when
linking (see :ref:`options-linker`), you can give RTS options on the command
line when running your program.
If you set the :ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]` flag
appropriately when linking (see :ref:`options-linker`), you can give RTS
options on the command line when running your program.
When your Haskell program starts up, the RTS extracts command-line
arguments bracketed between ``+RTS`` and ``-RTS`` as its own. For example:
......@@ -177,8 +177,8 @@ e.g., on stack overflow. The hooks for these are as follows:
Event log output
################
Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l`) is
written through a custom :c:type:`EventLogWriter`:
Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l
⟨flags⟩`) is written through a custom :c:type:`EventLogWriter`:
.. c:type:: EventLogWriter
......@@ -415,10 +415,10 @@ performance.
The compaction algorithm is slower than the copying algorithm, but
the savings in memory use can be considerable.
For a given heap size (using the :ghc-flag:`-H ⟨size⟩` option), compaction
can in fact reduce the GC cost by allowing fewer GCs to be performed. This
is more likely when the ratio of live data to heap size is high, say
greater than 30%.
For a given heap size (using the :rts-flag:`-H [⟨size⟩]` option),
compaction can in fact reduce the GC cost by allowing fewer GCs to be
performed. This is more likely when the ratio of live data to heap size is
high, say greater than 30%.
.. note::
Compaction doesn't currently work when a single generation is
......@@ -1104,7 +1104,8 @@ When the program is linked with the :ghc-flag:`-eventlog` option
:default: :file:`<program>.eventlog`
:since: 8.8
Sets the destination for the eventlog produced with the :rts-flag:`-l` flag.
Sets the destination for the eventlog produced with the
:rts-flag:`-l ⟨flags⟩` flag.
.. rts-flag:: -v [⟨flags⟩]
......@@ -1173,8 +1174,8 @@ recommended for everyday use!
.. rts-flag:: -DC DEBUG: compact
Debug messages will be sent to the binary event log file instead of
stdout if the :rts-flag:`-l` option is added. This might be useful for
reducing the overhead of debug tracing.
stdout if the :rts-flag:`-l ⟨flags⟩` option is added. This might be useful
for reducing the overhead of debug tracing.
To figure out what exactly they do, the least bad way is to grep the rts/ directory in
the ghc code for macros like ``DEBUG(scheduler`` or ``DEBUG_scheduler``.
......
......@@ -31,10 +31,10 @@ Use more memory:
single: -H; RTS option
If it says you're using more than 20% of total time in garbage collecting,
then more memory might help: use the ``-H⟨size⟩`` (see :rts-flag:`-H
[⟨size⟩]`) option. Increasing the default allocation area size used by the
compiler's RTS might also help: use the ``+RTS -A⟨size⟩ -RTS`` option (see
:rts-flag:`-A ⟨size⟩`).
then more memory might help: use the ``-H⟨size⟩`` (see
:rts-flag:`-H [⟨size⟩]`) option. Increasing the default allocation area
size used by the compiler's RTS might also help: use the ``+RTS -A⟨size⟩
-RTS`` option (see :rts-flag:`-A ⟨size⟩`).
.. index::
single: -A⟨size⟩; RTS option
......@@ -305,11 +305,12 @@ Use unboxed arrays (``UArray``)
Use a bigger heap!
If your program's GC stats (:rts-flag:`-S [⟨file⟩]` RTS option) indicate
that it's doing lots of garbage-collection (say, more than 20% of execution
time), more memory might help — with the :rts-flag:`-H⟨size⟩` or :rts-flag:`-A⟨size⟩` RTS
options (see :ref:`rts-options-gc`). As a rule of thumb, try setting
:rts-flag:`-H ⟨size⟩` to the amount of memory you're willing to let your process
consume, or perhaps try passing :ghc-flag:`-H ⟨size⟩` without any argument
to let GHC calculate a value based on the amount of live data.
time), more memory might help — with the :rts-flag:`-H [⟨size⟩]` or
:rts-flag:`-A ⟨size⟩` RTS options (see :ref:`rts-options-gc`). As a rule
of thumb, try setting :rts-flag:`-H [⟨size⟩]` to the amount of memory
you're willing to let your process consume, or perhaps try passing
:rts-flag:`-H [⟨size⟩]` without any argument to let GHC calculate a value
based on the amount of live data.
Compact your data:
The :ghc-compact-ref:`GHC.Compact.` module
......@@ -350,7 +351,7 @@ Thriftier: producing a program that gobbles less heap space
"I think I have a space leak..."
Re-run your program with :ghc-flag:`+RTS -S <-S [⟨file⟩]>`, and remove all
Re-run your program with :rts-flag:`+RTS -S <-S [⟨file⟩]>`, and remove all
doubt! (You'll see the heap usage get bigger and bigger...) (Hmmm... this might
be even easier with the :rts-flag:`-G1 <-G ⟨generations⟩>` RTS option; so...
``./a.out +RTS -S -G1``)
......
......@@ -319,9 +319,8 @@ of ``-W(no-)*``.
.. ghc-flag:: -Wpartial-type-signatures
:shortdesc: warn about holes in partial type signatures when
:extension:`PartialTypeSignatures` is enabled. Not applicable when
:extension:`PartialTypesignatures` is not enabled, in which case
errors are generated for such holes. See
:ref:`partial-type-signatures`.
:extension:`PartialTypeSignatures` is not enabled, in which case
errors are generated for such holes.
:type: dynamic
:reverse: -Wno-partial-type-signatures
:category:
......@@ -643,15 +642,15 @@ of ``-W(no-)*``.
.. ghc-flag:: -Wderiving-defaults
:shortdesc: warn about default deriving when using both
DeriveAnyClass and GeneralizedNewtypeDeriving
:extension:`DeriveAnyClass` and :extension:`GeneralizedNewtypeDeriving`
:type: dynamic
:reverse: -Wno-deriving-defaults
:category:
:since: 8.10
Causes a warning when both :ref:`DeriveAnyClass` and
:ref:`GeneralizedNewtypeDeriving` are enabled and no explicit
Causes a warning when both :extension:`DeriveAnyClass` and
:extension:`GeneralizedNewtypeDeriving` are enabled and no explicit
deriving strategy is in use. For example, this would result a
warning: ::
......@@ -756,6 +755,24 @@ of ``-W(no-)*``.
probably no-ops and can be omitted. The functions checked for are:
``toInteger``, ``toRational``, ``fromIntegral``, and ``realToFrac``.
.. ghc-flag:: -Wimplicit-kind-vars
:shortdesc: warn when kind variables are implicitly quantified over.
:type: dynamic
:reverse: -Wno-implicit-kind-vars
:category:
.. index::
single: implicit prelude, warning
Have the compiler warn if a kind variable is not explicitly quantified
over. For instance, the following would produce a warning: ::
f :: forall (a :: k). Proxy a
This can be fixed by explicitly quantifying over ``k``: ::
f :: forall k (a :: k). Proxy a
.. ghc-flag:: -Wimplicit-prelude
:shortdesc: warn when the Prelude is implicitly imported
:type: dynamic
......@@ -835,7 +852,7 @@ of ``-W(no-)*``.
``Just y`` but ``y`` is not ``4``.
This can be exponential in the arity of the pattern and in the number of
guards in some cases. The :ghc-flag:`-fmax-pmcheck-models` limit makes sure
guards in some cases. The :ghc-flag:`-fmax-pmcheck-models=⟨n⟩` limit makes sure
we scale polynomially in the number of patterns, by forgetting refined
information gained from a partially successful match. For the above example,
if we had a limit of 1, we would continue checking the next clause with the
......@@ -1705,8 +1722,9 @@ of ``-W(no-)*``.
:since: 8.8
The option :ghc-flag:`-Wunused-packages` warns about packages, specified on
command line via :ghc-flag:`-package` or :ghc-flag:`-package-id`, but were not
loaded during compication. Usually it means that you have an unused dependency.
command line via :ghc-flag:`-package ⟨pkg⟩` or
:ghc-flag:`-package-id ⟨unit-id⟩`, but were not loaded during compication.
Usually it means that you have an unused dependency.
You may want to enable this warning on a clean build or enable :ghc-flag:`-fforce-recomp`
in order to get reliable results.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment