diff options
Diffstat (limited to 'docs/users_guide/using.rst')
| -rw-r--r-- | docs/users_guide/using.rst | 159 |
1 files changed, 153 insertions, 6 deletions
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst index 6dde0ee423..a963ead8f1 100644 --- a/docs/users_guide/using.rst +++ b/docs/users_guide/using.rst @@ -258,6 +258,10 @@ to produce an executable. The available mode flags are: .. ghc-flag:: --interactive + :shortdesc: Interactive mode - normally used by just running ``ghci``; + see :ref:`ghci` for details. + :type: mode + :category: modes .. index:: single: interactive mode @@ -267,6 +271,11 @@ The available mode flags are: mode is described in more detail in :ref:`ghci`. .. ghc-flag:: --make + :shortdesc: Build a multi-module Haskell program, automatically figuring out + dependencies. Likely to be much easier, and faster, than using + ``make``; see :ref:`make-mode` for details. + :type: mode + :category: modes .. index:: single: make mode; of GHC @@ -282,6 +291,9 @@ The available mode flags are: option can be omitted. .. ghc-flag:: -e ⟨expr⟩ + :shortdesc: Evaluate ``expr``; see :ref:`eval-mode` for details. + :type: mode + :category: modes .. index:: single: eval mode; of GHC @@ -292,15 +304,42 @@ The available mode flags are: details. .. ghc-flag:: -E - -C - -S - -c + :shortdesc: Stop after preprocessing (``.hspp`` file) + :type: mode + :category: phases + + Stop after preprocessing (``.hspp`` file) + +.. ghc-flag:: -C + :shortdesc: Stop after generating C (``.hc`` file) + :type: mode + :category: phases + + Stop after generating C (``.hc`` file) + +.. ghc-flag:: -S + :shortdesc: Stop after generating assembly (``.s`` file) + :type: mode + :category: phases + + Stop after generating assembly (``.s`` file) + +.. ghc-flag:: -c + :shortdesc: Stop after generating object (``.o``) file + :type: mode + :category: phases + + Stop after generating object (``.o``) file This is the traditional batch-compiler mode, in which GHC can compile source files one at a time, or link objects together into an executable. See :ref:`options-order`. .. ghc-flag:: -M + :shortdesc: generate dependency information suitable for use in a + ``Makefile``; see :ref:`makefile-dependencies` for details. + :type: mode + :category: modes .. index:: single: dependency-generation mode; of GHC @@ -310,6 +349,10 @@ The available mode flags are: See :ref:`makefile-dependencies`. .. ghc-flag:: --frontend ⟨module⟩ + :shortdesc: run GHC with the given frontend plugin; see + :ref:`frontend_plugins` for details. + :type: mode + :category: modes .. index:: single: frontend plugins; using @@ -318,6 +361,9 @@ The available mode flags are: details. .. ghc-flag:: --mk-dll + :shortdesc: DLL-creation mode (Windows only) + :type: mode + :category: modes .. index:: single: DLL-creation mode @@ -326,39 +372,63 @@ The available mode flags are: .. ghc-flag:: --help -? + :shortdesc: Display help + :type: mode + :category: modes Cause GHC to spew a long usage message to standard output and then exit. .. ghc-flag:: --show-iface ⟨file⟩ + :shortdesc: display the contents of an interface file. + :type: mode + :category: modes Read the interface in ⟨file⟩ and dump it as text to ``stdout``. For example ``ghc --show-iface M.hi``. .. ghc-flag:: --supported-extensions --supported-languages + :shortdesc: display the supported language extensions + :type: mode + :category: modes Print the supported language extensions. .. ghc-flag:: --show-options + :shortdesc: display the supported command line options + :type: mode + :category: modes Print the supported command line options. This flag can be used for autocompletion in a shell. .. ghc-flag:: --info + :shortdesc: display information about the compiler + :type: mode + :category: modes Print information about the compiler. .. ghc-flag:: --version -V + :shortdesc: display GHC version + :type: mode + :category: modes Print a one-line string including GHC's version number. .. ghc-flag:: --numeric-version + :shortdesc: display GHC version (numeric only) + :type: mode + :category: modes Print GHC's numeric version number only. .. ghc-flag:: --print-libdir + :shortdesc: display GHC library directory + :type: mode + :category: modes .. index:: single: libdir @@ -446,6 +516,10 @@ directory; the :ghc-flag:`-i` option can be used to add directories to the search path (see :ref:`search-path`). .. ghc-flag:: -j[⟨n⟩] + :shortdesc: When compiling with :ghc-flag:`--make`, compile ⟨n⟩ modules + in parallel. + :type: dynamic + :category: misc Perform compilation in parallel when possible. GHC will use up to ⟨N⟩ threads during compilation. If N is omitted, then it defaults to the @@ -554,6 +628,9 @@ suffix. This behaviour can be overridden using the :ghc-flag:`-x ⟨suffix⟩` option: .. ghc-flag:: -x ⟨suffix⟩ + :shortdesc: Override default behaviour for source files + :type: dynamic + :category: phases Causes all files following this option on the command line to be processed as if they had the suffix ⟨suffix⟩. For example, to @@ -572,6 +649,9 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and ``--print-libdir`` modes in :ref:`modes`. .. ghc-flag:: -v + :shortdesc: verbose mode (equivalent to ``-v3``) + :type: dynamic + :category: verbosity The :ghc-flag:`-v` option makes GHC *verbose*: it reports its version number and shows (on stderr) exactly how it invokes each phase of the @@ -583,8 +663,10 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and Knowing that you ran the right bits in the right order is always the first thing we want to verify. -.. ghc-flag:: -v ⟨n⟩ - :noindex: +.. ghc-flag:: -v⟨n⟩ + :shortdesc: set verbosity level + :type: dynamic + :category: verbosity To provide more control over the compiler's verbosity, the ``-v`` flag takes an optional numeric argument. Specifying ``-v`` on its @@ -613,12 +695,19 @@ See also the ``--help``, ``--version``, ``--numeric-version``, and (excluding preprocessed and C/assembly files). .. ghc-flag:: -fprint-potential-instances + :shortdesc: display all available instances in type error messages + :type: dynamic + :reverse: -fno-print-potential-instances + :category: verbosity When GHC can't find an instance for a class, it displays a short list of some in the instances it knows about. With this flag it prints *all* the instances it knows about. .. ghc-flag:: -fhide-source-paths + :shortdesc: hide module source and object paths + :type: dynamic + :category: verbosity Starting with minimal verbosity (``-v1``, see :ghc-flag:`-v`), GHC displays the name, the source path and the target path of each compiled @@ -629,6 +718,11 @@ The following flags control the way in which GHC displays types in error messages and in GHCi: .. ghc-flag:: -fprint-unicode-syntax + :shortdesc: Use unicode syntax when printing expressions, types and kinds. + See also :ghc-flag:`-XUnicodeSyntax` + :type: dynamic + :reverse: -fno-print-unicode-syntax + :category: verbosity When enabled GHC prints type signatures using the unicode symbols from the :ghc-flag:`-XUnicodeSyntax` extension. For instance, @@ -642,6 +736,11 @@ messages and in GHCi: .. _pretty-printing-types: .. ghc-flag:: -fprint-explicit-foralls + :shortdesc: Print explicit ``forall`` quantification in types. + See also :ghc-flag:`-XExplicitForAll` + :type: dynamic + :reverse: -fno-print-explicit-foralls + :category: verbosity Using :ghc-flag:`-fprint-explicit-foralls` makes GHC print explicit ``forall`` quantification at the top level of a @@ -678,6 +777,11 @@ messages and in GHCi: -- Defined in Data.Type.Equality .. ghc-flag:: -fprint-explicit-kinds + :shortdesc: Print explicit kind foralls and kind arguments in types. + See also :ghc-flag:`-XKindSignatures` + :type: dynamic + :reverse: -fno-print-explicit-kinds + :category: verbosity Using :ghc-flag:`-fprint-explicit-kinds` makes GHC print kind arguments in types, which are normally suppressed. This can be important when you @@ -694,6 +798,11 @@ messages and in GHCi: MkT :: forall (k :: BOX) (a :: k). T k a .. ghc-flag:: -fprint-explicit-runtime-reps + :shortdesc: Print ``RuntimeRep`` variables in types which are + runtime-representation polymorphic. + :type: dynamic + :reverse: -fno-print-explicit-runtime-reps + :category: verbosity When :ghc-flag:`-fprint-explicit-runtime-reps` is enabled, GHC prints ``RuntimeRep`` type variables for levity-polymorphic types. @@ -710,6 +819,10 @@ messages and in GHCi: (a -> b) -> a -> b .. ghc-flag:: -fprint-explicit-coercions + :shortdesc: Print coercions in types + :type: dynamic + :reverse: -fno-print-explicit-coercions + :category: verbosity Using :ghc-flag:`-fprint-explicit-coercions` makes GHC print coercions in types. When trying to prove the equality between types of different @@ -717,6 +830,10 @@ messages and in GHCi: see these, as they are meant to be internal. .. ghc-flag:: -fprint-equality-relations + :shortdesc: Distinguish between equality relations when printing + :type: dynamic + :reverse: -fno-print-equality-relations + :category: verbosity Using :ghc-flag:`-fprint-equality-relations` tells GHC to distinguish between its equality relations when printing. For example, ``~`` is homogeneous @@ -729,6 +846,10 @@ messages and in GHCi: prints all of these as ``~``. See also :ref:`equality-constraints`. .. ghc-flag:: -fprint-expanded-synonyms + :shortdesc: In type errors, also print type-synonym-expanded types. + :type: dynamic + :reverse: -fno-print-expanded-synonyms + :category: verbosity When enabled, GHC also prints type-synonym-expanded types in type errors. For example, with this type synonyms: :: @@ -757,6 +878,10 @@ messages and in GHCi: Actual type: ST s Bool .. ghc-flag:: -fprint-typechecker-elaboration + :shortdesc: Print extra information from typechecker. + :type: dynamic + :reverse: -fno-print-typechecker-elaboration + :category: verbosity When enabled, GHC also prints extra information from the typechecker in warnings. For example: :: @@ -794,6 +919,9 @@ messages and in GHCi: or by using the flag -fno-warn-unused-do-bind .. ghc-flag:: -fdiagnostics-color=⟨always|auto|never⟩ + :shortdesc: Use colors in error messages + :type: dynamic + :category: verbosity Causes GHC to display error messages with colors. To do this, the terminal must have support for ANSI color codes, or else garbled text will @@ -833,13 +961,20 @@ messages and in GHCi: or ``always``, which is equivalent to setting the corresponding ``-fdiagnostics-color`` flag but with lower precedence. -.. ghc-flag:: -f[no-]diagnostics-show-caret +.. ghc-flag:: -fdiagnostics-show-caret + :shortdesc: Whether to show snippets of original source code + :type: dynamic + :reverse: -fno-diagnostics-show-caret + :category: verbosity Controls whether GHC displays a line of the original source code where the error was detected. This also affects the associated caret symbol that points at the region of code at fault. The flag is on by default. .. ghc-flag:: -ferror-spans + :shortdesc: Output full span in error messages + :type: dynamic + :category: verbosity Causes GHC to emit the full source span of the syntactic entity relating to an error message. Normally, GHC emits the source @@ -872,11 +1007,17 @@ messages and in GHCi: (i.e. this is how Emacs does it). .. ghc-flag:: -H ⟨size⟩ + :shortdesc: Set the minimum size of the heap to ⟨size⟩ + :type: dynamic + :category: misc Set the minimum size of the heap to ⟨size⟩. This option is equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`. .. ghc-flag:: -Rghc-timing + :shortdesc: Summarise timing stats for GHC (same as ``+RTS -tstderr``). + :type: dynamic + :category: verbosity Prints a one-line summary of timing statistics for the GHC run. This option is equivalent to ``+RTS -tstderr``, see @@ -895,6 +1036,9 @@ Platform-specific Flags Some flags only make sense for particular target platforms. .. ghc-flag:: -msse2 + :shortdesc: (x86 only) Use SSE2 for floating-point operations + :type: dynamic + :category: platform-options (x86 only, added in GHC 7.0.1) Use the SSE2 registers and instruction set to implement floating point operations when using @@ -909,6 +1053,9 @@ Some flags only make sense for particular target platforms. SSE2 is unconditionally used on x86-64 platforms. .. ghc-flag:: -msse4.2 + :shortdesc: (x86 only) Use SSE4.2 for floating-point operations + :type: dynamic + :category: platform-options (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to implement some floating point and bit operations when using the |