Commit a6c3289d authored by Ben Gamari's avatar Ben Gamari 🐢
Browse files

users_guide: Use semantic directive/role for command line options

And GHCi commands. This makes cross-referencing much easier.

Also normalize markup a bit and add some missing flags.
parent 1cdf12c4
......@@ -22,14 +22,14 @@ The highlights, since the 7.10 branch, are:
- More reliable DWARF debugging information
- Support for :ref:`injective type classes :ref:`injective-ty-fams`
- Support for :ref:`injective type classes <injective-ty-fams>`
- Applicative ``do`` notation (see :ref:`applicative-do`)
- Support for wildcards in data and type family instances
- ``Strict`` and ``StrictData`` extensions, allowing modules to be compiled with
strict-by-default bindings (see :ref:`strict-haskell`)
strict-by-default bindings (see :ref:`strict-haskell`)
- ``DuplicateRecordFields``, allowing multiple datatypes to declare the same
record field names provided they are used unambiguously (see :ref:`duplicate-record-fields`)
......
......@@ -26,9 +26,9 @@ Divergence from Haskell 98 and Haskell 2010
By default, GHC mainly aims to behave (mostly) like a Haskell 2010
compiler, although you can tell it to try to behave like a particular
version of the language with the ``-XHaskell98`` and ``-XHaskell2010``
flags. The known deviations from the standards are described below.
Unless otherwise stated, the deviation applies in Haskell 98,
version of the language with the :ghc-flag:`-XHaskell98` and
:ghc-flag:`-XHaskell2010` flags. The known deviations from the standards are
described below. Unless otherwise stated, the deviation applies in Haskell 98,
Haskell 2010 and the default modes.
.. _infelicities-lexical:
......@@ -54,9 +54,7 @@ Context-free syntax
relaxed to allow the nested context to be at the same level as the
enclosing context, if the enclosing context is a ``do`` expression.
For example, the following code is accepted by GHC:
::
For example, the following code is accepted by GHC: ::
main = do args <- getArgs
if null args then return [] else do
......@@ -69,15 +67,11 @@ Context-free syntax
- GHC doesn't do the fixity resolution in expressions during parsing as
required by Haskell 98 (but not by Haskell 2010). For example,
according to the Haskell 98 report, the following expression is
legal:
::
legal: ::
let x = 42 in x == 42 == True
and parses as:
::
and parses as: ::
(let x = 42 in x == 42) == True
......@@ -85,11 +79,10 @@ Context-free syntax
far to the right as possible”. Since it can't extend past the second
equals sign without causing a parse error (``==`` is non-fix), the
``let``\-expression must terminate there. GHC simply gobbles up the
whole expression, parsing like this:
::
whole expression, parsing like this: ::
(let x = 42 in x == 42 == True)
- The Haskell Report allows you to put a unary ``-`` preceding certain
expressions headed by keywords, allowing constructs like ``- case x of ...``
or ``- do { ... }``. GHC does not allow this. Instead, unary ``-`` is allowed
......@@ -102,9 +95,7 @@ Expressions and patterns
^^^^^^^^^^^^^^^^^^^^^^^^
In its default mode, GHC makes some programs slightly more defined than
they should be. For example, consider
::
they should be. For example, consider ::
f :: [a] -> b -> b
f [] = error "urk"
......@@ -188,9 +179,7 @@ Numbers, basic types, and built-in classes
in ``Bits`` instances.
Extra instances
The following extra instances are defined:
::
The following extra instances are defined: ::
instance Functor ((->) r)
instance Monad ((->) r)
......@@ -199,9 +188,7 @@ Extra instances
instance Monad (Either e)
Multiply-defined array elements not checked
This code fragment should elicit a fatal error, but it does not:
::
This code fragment should elicit a fatal error, but it does not: ::
main = print (array (1,1) [(1,2), (1,3)])
......@@ -223,31 +210,23 @@ Arbitrary-sized tuples
stuck on it.
``splitAt`` semantics
``Data.List.splitAt`` is stricter than specified in the Report.
Specifically, the Report specifies that
..
``Data.List.splitAt`` is more strict than specified in the Report.
Specifically, the Report specifies that ::
splitAt n xs = (take n xs, drop n xs)
which implies that
..
which implies that ::
splitAt undefined undefined = (undefined, undefined)
but GHC's implementation is strict in its first argument, so
but GHC's implementation is strict in its first argument, so ::
..
splitAt undefined [] = undefined
splitAt undefined [] = undefined
``Read``\ ing integers
GHC's implementation of the ``Read`` class for integral types
accepts hexadecimal and octal literals (the code in the Haskell 98
report doesn't). So, for example,
::
report doesn't). So, for example, ::
read "0xf00" :: Int
......@@ -258,9 +237,7 @@ Arbitrary-sized tuples
too.
``isAlpha``
The Haskell 98 definition of ``isAlpha`` is:
::
The Haskell 98 definition of ``isAlpha`` is: ::
isAlpha c = isUpper c || isLower c
......@@ -377,17 +354,17 @@ Bugs in GHC
for further discussion.
If you are hit by this, you may want to compile the affected module
with ``-fno-omit-yields`` (see :ref:`options-f`). This flag ensures that
yield points are inserted at every function entrypoint (at the expense of a
bit of performance).
with :ghc-flag:`-fno-omit-yields <-fomit-yields>` (see :ref:`options-f`).
This flag ensures that yield points are inserted at every function entrypoint
(at the expense of a bit of performance).
- GHC's updated exhaustiveness and coverage checker (see
:ref:`options-sanity`) is quite expressive but with a rather high
performance cost (in terms of both time and memory consumption), mainly
due to guards. Two flags have been introduced to give more control to
the user over guard reasoning: ``-Wtoo-many-guards``
and ``-ffull-guard-reasoning`` (see :ref:`options-sanity`).
When ``-ffull-guard-reasoning`` is on, pattern match checking for guards
the user over guard reasoning: :ghc-flag:`-Wtoo-many-guards`
and :ghc-flag:`-ffull-guard-reasoning` (see :ref:`options-sanity`).
When :ghc-flag:`-ffull-guard-reasoning` is on, pattern match checking for guards
runs in full power, which may run out of memory/substantially increase
compilation time.
......@@ -426,7 +403,7 @@ Bugs in GHC
The non-termination is reported like this:
::
.. code-block:: none
ghc: panic! (the 'impossible' happened)
(GHC version 7.10.1 for x86_64-unknown-linux):
......@@ -435,7 +412,7 @@ Bugs in GHC
To increase the limit, use -fsimpl-tick-factor=N (default 100)
with the panic being reported no matter how high a
``-fsimpl-tick-factor`` you supply.
:ghc-flag:`-fsimpl-tick-factor` you supply.
We have never found another class of programs, other than this
contrived one, that makes GHC diverge, and fixing the problem would
......@@ -444,7 +421,7 @@ Bugs in GHC
inliner <http://research.microsoft.com/~simonpj/Papers/inlining/>`__.
- On 32-bit x86 platforms when using the native code generator, the
``-fexcess-precision``\ ``-fexcess-precision`` option is always on.
:ghc-flag:`-fexcess-precision` option is always on.
This means that floating-point calculations are non-deterministic,
because depending on how the program is compiled (optimisation
settings, for example), certain calculations might be done at 80-bit
......@@ -457,8 +434,8 @@ Bugs in GHC
.. index::
single: -msse2 option
One workaround is to use the ``-msse2`` option (see
:ref:`options-platform`, which generates code to use the SSE2
One workaround is to use the :ghc-flag:`-msse2` option (see
:ref:`options-platform`), which generates code to use the SSE2
instruction set instead of the x87 instruction set. SSE2 code uses
the correct precision for all floating-point operations, and so gives
deterministic results. However, note that this only works with
......@@ -490,7 +467,7 @@ Bugs in GHCi (the interactive GHC)
files that have more than 0xffff relocations. When GHCi tries to load
a package affected by this bug, you get an error message of the form
::
.. code-block:: none
Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765)
......
......@@ -111,16 +111,63 @@ texinfo_documents = [
'Compilers'),
]
from sphinx import addnodes
from docutils import nodes
def parse_ghci_cmd(env, sig, signode):
from sphinx import addnodes
name = sig.split(';')[0]
sig = sig.replace(';', '')
signode += addnodes.desc_name(name, sig)
return name
def parse_flag(env, sig, signode):
import re
names = []
for i, flag in enumerate(sig.split(',')):
flag = flag.strip()
equals = '='
parts = flag.split('=')
if len(parts) == 1:
equals=''
parts = flag.split()
if len(parts) == 0: continue
name = parts[0]
names.append(name)
sig = equals + ' '.join(parts[1:])
sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
if i > 0:
signode += addnodes.desc_name(', ', ', ')
signode += addnodes.desc_name(name, name)
if len(sig) > 0:
signode += addnodes.desc_addname(sig, sig)
return names[0]
def setup(app):
from sphinx.util.docfields import Field, TypedField
# the :ghci-cmd: directive used in ghci.rst
app.add_object_type('ghci-cmd', 'ghci-cmd',
parse_node=parse_ghci_cmd,
objname='GHCi command',
indextemplate='pair: %s; GHCi command')
app.add_object_type('ghc-flag', 'ghc-flag',
objname='GHC command-line option',
parse_node=parse_flag,
indextemplate='pair: %s; GHC option',
doc_field_types=[
Field('since', label='Introduced in GHC version', names=['since']),
Field('default', label='Default value', names=['default']),
Field('static')
])
app.add_object_type('rts-flag', 'rts-flag',
objname='runtime system command-line option',
parse_node=parse_flag,
indextemplate='pair: %s; RTS option',
doc_field_types=[
Field('since', label='Introduced in GHC version', names=['since']),
Field('static')
])
......@@ -25,259 +25,188 @@ Dumping out compiler intermediate structures
need a short form…). You can get all of these at once (*lots* of
output) by using ``-v5``, or most of them with ``-v4``. You can
prevent them from clogging up your standard output by passing
``-ddump-to-file``. Some of the most useful ones are:
:ghc-flag:`-ddump-to-file`. Some of the most useful ones are:
``-ddump-parsed``
.. index::
single: -ddump-parsed
.. ghc-flag:: -ddump-to-file
Causes the output from all of the flags listed below to be dumped
to a file. The file name depends upon the output produced; for instance,
output from :ghc-flag:`-ddump-simpl` will end up in
:file:`{module}.dump-simpl`.
.. ghc-flag:: -ddump-parsed
Dump parser output
``-ddump-rn``
.. index::
single: -ddump-rn
.. ghc-flag:: -ddump-rn
Dump renamer output
``-ddump-tc``
.. index::
single: -ddump-tc
.. ghc-flag:: -ddump-tc
Dump typechecker output
``-ddump-splices``
.. index::
single: -ddump-splices
.. ghc-flag:: -ddump-splices
Dump Template Haskell expressions that we splice in, and what
Haskell code the expression evaluates to.
``-ddump-types``
.. index::
single: -ddump-types
.. ghc-flag:: -ddump-types
Dump a type signature for each value defined at the top level of
the module. The list is sorted alphabetically. Using
``-dppr-debug`` dumps a type signature for all the imported and
:ghc-flag:`-dppr-debug` dumps a type signature for all the imported and
system-defined things as well; useful for debugging the
compiler.
``-ddump-deriv``
.. index::
single: -ddump-deriv
.. ghc-flag:: -ddump-deriv
Dump derived instances
``-ddump-ds``
.. index::
single: -ddump-ds
.. ghc-flag:: -ddump-ds
Dump desugarer output
``-ddump-spec``
.. index::
single: -ddump-spec
.. ghc-flag:: -ddump-spec
Dump output of specialisation pass
``-ddump-rules``
.. index::
single: -ddump-rules
.. ghc-flag:: -ddump-rules
Dumps all rewrite rules specified in this module; see
:ref:`controlling-rules`.
``-ddump-rule-firings``
.. index::
single: -ddump-rule-firings
.. ghc-flag:: -ddump-rule-firings
Dumps the names of all rules that fired in this module
``-ddump-rule-rewrites``
.. index::
single: -ddump-rule-rewrites
.. ghc-flag:: -ddump-rule-rewrites
Dumps detailed information about all rules that fired in this
module
``-ddump-vect``
.. index::
single: -ddump-vect
.. ghc-flag:: -ddump-vect
Dumps the output of the vectoriser.
``-ddump-simpl``
.. index::
single: -ddump-simpl
.. ghc-flag:: -ddump-simpl
Dump simplifier output (Core-to-Core passes)
``-ddump-inlinings``
.. index::
single: -ddump-inlinings
.. ghc-flag:: -ddump-inlinings
Dumps inlining info from the simplifier
``-ddump-stranal``
.. index::
single: -ddump-stranal
.. ghc-flag:: -ddump-stranal
Dump strictness analyser output
``-ddump-strsigs``
.. index::
single: -ddump-strsigs
.. ghc-flag:: -ddump-strsigs
Dump strictness signatures
``-ddump-cse``
.. index::
single: -ddump-cse
.. ghc-flag:: -ddump-cse
Dump common subexpression elimination (CSE) pass output
``-ddump-worker-wrapper``
.. index::
single: -ddump-worker-wrapper
.. ghc-flag:: -ddump-worker-wrapper
Dump worker/wrapper split output
``-ddump-occur-anal``
.. index::
single: -ddump-occur-anal
.. ghc-flag:: -ddump-occur-anal
Dump "occurrence analysis" output
``-ddump-prep``
.. index::
single: -ddump-prep
.. ghc-flag:: -ddump-prep
Dump output of Core preparation pass
``-ddump-stg``
.. index::
single: -ddump-stg
.. ghc-flag:: -ddump-stg
Dump output of STG-to-STG passes
``-ddump-cmm``
.. index::
single: -ddump-cmm
.. ghc-flag:: -ddump-cmm
Print the C-- code out.
``-ddump-opt-cmm``
.. index::
single: -ddump-opt-cmm
.. ghc-flag:: -ddump-opt-cmm
Dump the results of C-- to C-- optimising passes.
``-ddump-asm``
.. index::
single: -ddump-asm
.. ghc-flag:: -ddump-asm
Dump assembly language produced by the :ref:`native code
generator <native-code-gen>`
``-ddump-llvm``
.. index::
single: -ddump-llvm
.. ghc-flag:: -ddump-llvm
LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
``-ddump-bcos``
.. index::
single: -ddump-bcos
.. ghc-flag:: -ddump-bcos
Dump byte-code compiler output
``-ddump-foreign``
.. index::
single: -ddump-foreign
.. ghc-flag:: -ddump-foreign
dump foreign export stubs
``-ddump-simpl-iterations``
.. index::
single: -ddump-simpl-iterations
.. ghc-flag:: -ddump-simpl-iterations
Show the output of each *iteration* of the simplifier (each run of
the simplifier has a maximum number of iterations, normally 4). This
outputs even more information than ``-ddump-simpl-phases``.
``-ddump-simpl-stats``
.. index::
single: -ddump-simpl-stats option
.. ghc-flag:: -ddump-simpl-stats
Dump statistics about how many of each kind of transformation too
place. If you add ``-dppr-debug`` you get more detailed information.
``-ddump-if-trace``
.. index::
single: -ddump-if-trace
.. ghc-flag:: -ddump-if-trace
Make the interface loader be *real* chatty about what it is up to.
``-ddump-tc-trace``
.. index::
single: -ddump-tc-trace
.. ghc-flag:: -ddump-tc-trace
Make the type checker be *real* chatty about what it is up to.
``-ddump-vt-trace``
.. index::
single: -ddump-tv-trace
.. ghc-flag:: -ddump-vt-trace
Make the vectoriser be *real* chatty about what it is up to.
``-ddump-rn-trace``
.. index::
single: -ddump-rn-trace
.. ghc-flag:: -ddump-rn-trace
Make the renamer be *real* chatty about what it is up to.
``-ddump-rn-stats``
.. index::
single: -dshow-rn-stats
.. ghc-flag:: -ddump-rn-stats
Print out summary of what kind of information the renamer had to
bring in.
``-dverbose-core2core``, ``-dverbose-stg2stg``
.. index::
single: -dverbose-core2core
single: -dverbose-stg2stg
.. ghc-flag:: -dverbose-core2core
-dverbose-stg2stg
Show the output of the intermediate Core-to-Core and STG-to-STG
passes, respectively. (*lots* of output!) So: when we're really
desperate:
::
.. code-block:: sh
% ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
``-dshow-passes``
.. index::
single: -dshow-passes
.. ghc-flag:: -dshow-passes
Print out each pass name as it happens.
``-ddump-core-stats``
.. index::
single: -ddump-core-stats
.. ghc-flag:: -ddump-core-stats
Print a one-line summary of the size of the Core program at the end
of the optimisation pipeline.
``-dfaststring-stats``
.. index::
single: -dfaststring-stats
.. ghc-flag:: -dfaststring-stats
Show statistics on the usage of fast strings by the compiler.
``-dppr-debug``
.. index::
single: -dppr-debug
.. ghc-flag:: -dppr-debug
Debugging output is in one of several "styles." Take the printing of
types, for example. In the "user" style (the default), the
......@@ -342,63 +271,47 @@ Core dumps contain a large amount of information. Depending on what you
are doing, not all of it will be useful. Use these flags to suppress the
parts that you are not interested in.
``-dsuppress-all``
.. index::
single: -dsuppress-all
.. ghc-flag:: -dsuppress-all
Suppress everything that can be suppressed, except for unique ids as
this often makes the printout ambiguous. If you just want to see the
overall structure of the code, then start here.
``-dsuppress-uniques``
.. index::
single: -dsuppress-uniques
.. ghc-flag:: -dsuppress-uniques
Suppress the printing of uniques. This may make the printout
ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
makes the output of two compiler runs have many fewer gratuitous
differences, so you can realistically apply ``diff``. Once ``diff``
has shown you where to look, you can try again without
``-dsuppress-uniques``
:ghc-flag:`-dsuppress-uniques`
``-dsuppress-idinfo``
.. index::
single: -dsuppress-idinfo
.. ghc-flag:: -dsuppress-idinfo
Suppress extended information about identifiers where they are
bound. This includes strictness information and inliner templates.
Using this flag can cut the size of the core dump in half, due to
the lack of inliner templates
``-dsuppress-unfoldings``
.. index::
single: -dsuppress-unfoldings
.. ghc-flag:: -dsuppress-unfoldings
Suppress the printing of the stable unfolding of a variable at its
binding site.
``-dsuppress-module-prefixes``
.. index::
single: -dsuppress-module-prefixes
.. ghc-flag:: -dsuppress-module-prefixes
Suppress the printing of module qualification prefixes. This is the
``Data.List`` in ``Data.List.length``.