diff options
Diffstat (limited to 'docs/users_guide')
| -rw-r--r-- | docs/users_guide/8.2.1-notes.rst | 4 | ||||
| -rw-r--r-- | docs/users_guide/conf.py | 52 | ||||
| -rw-r--r-- | docs/users_guide/debug-info.rst | 3 | ||||
| -rw-r--r-- | docs/users_guide/debugging.rst | 8 | ||||
| -rw-r--r-- | docs/users_guide/editing-guide.rst | 26 | ||||
| -rw-r--r-- | docs/users_guide/extending_ghc.rst | 65 | ||||
| -rw-r--r-- | docs/users_guide/ffi-chap.rst | 14 | ||||
| -rw-r--r-- | docs/users_guide/ghci.rst | 38 | ||||
| -rw-r--r-- | docs/users_guide/glasgow_exts.rst | 44 | ||||
| -rw-r--r-- | docs/users_guide/packages.rst | 82 | ||||
| -rw-r--r-- | docs/users_guide/phases.rst | 86 | ||||
| -rw-r--r-- | docs/users_guide/profiling.rst | 89 | ||||
| -rw-r--r-- | docs/users_guide/runtime_control.rst | 161 | ||||
| -rw-r--r-- | docs/users_guide/separate_compilation.rst | 48 | ||||
| -rw-r--r-- | docs/users_guide/shared_libs.rst | 21 | ||||
| -rw-r--r-- | docs/users_guide/sooner.rst | 34 | ||||
| -rw-r--r-- | docs/users_guide/using-concurrent.rst | 18 | ||||
| -rw-r--r-- | docs/users_guide/using-optimisation.rst | 55 | ||||
| -rw-r--r-- | docs/users_guide/using-warnings.rst | 6 | ||||
| -rw-r--r-- | docs/users_guide/using.rst | 21 |
20 files changed, 446 insertions, 429 deletions
diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst index e2231ba83f..d3ec4476c2 100644 --- a/docs/users_guide/8.2.1-notes.rst +++ b/docs/users_guide/8.2.1-notes.rst @@ -328,9 +328,9 @@ Runtime system This is supported on Linux and Windows systems. - The garbage collector can be told to use fewer threads than the - global number of capabilities set by :rts-flag:`-N`. By default, the garbage + global number of capabilities set by :rts-flag:`-N ⟨x⟩`. By default, the garbage collector will use a number of threads equal to the lesser of the global number - of capabilities or the number of physical cores. See :rts-flag:`-qn`, and a + of capabilities or the number of physical cores. See :rts-flag:`-qn ⟨x⟩`, and a `blog post <http://simonmar.github.io/posts/2016-12-08-Haskell-in-the-datacentre.html>`_ that describes this. diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py index 8a4c18f53e..12ecee9beb 100644 --- a/docs/users_guide/conf.py +++ b/docs/users_guide/conf.py @@ -116,35 +116,39 @@ texinfo_documents = [ from sphinx import addnodes from docutils import nodes +# The following functions parse flag declarations, and then have two jobs. First +# they modify the docutils node `signode` for the proper display of the +# declaration. Second, they return the name used to reference the flag. +# (i.e. return "name" implies you reference the flag with :flag:`name`) def parse_ghci_cmd(env, sig, signode): - name = sig.split(';')[0] - sig = sig.replace(';', '') - signode += addnodes.desc_name(name, sig) + parts = sig.split(';') + name = parts[0] + args = '' + if len(parts) > 1: + args = parts[1] + # Bold name + signode += addnodes.desc_name(name, name) + # Smaller args + signode += addnodes.desc_addname(args, args) + # Reference name return name def parse_flag(env, sig, signode): + + # Break flag into name and args import re - names = [] - for i, flag in enumerate(sig.split(',')): - flag = flag.strip() - sep = '=' - parts = flag.split('=') - if len(parts) == 1: - sep=' ' - parts = flag.split() - if len(parts) == 0: continue - - name = parts[0] - names.append(name) - sig = sep + ' '.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] + parts = re.split('( |=|\\[)', sig, 1) + flag = parts[0] + args = '' + if len(parts) > 1: + args = ''.join(parts[1:]) + + # Bold printed name + signode += addnodes.desc_name(flag, flag) + # Smaller arguments + signode += addnodes.desc_addname(args, args) + # Reference name left unchanged + return sig def setup(app): from sphinx.util.docfields import Field, TypedField diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst index a0aade5ecc..b4056007b1 100644 --- a/docs/users_guide/debug-info.rst +++ b/docs/users_guide/debug-info.rst @@ -5,7 +5,8 @@ Since the 7.10 release GHC can emit a debugging information to help debugging tools understand the code that GHC produces. This debugging information is useable by most UNIX debugging tools. -.. ghc-flag:: -g, -g<n> +.. ghc-flag:: -g + -g⟨n⟩ :since: 7.10, numeric levels since 8.0 diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst index af937ae64d..bc155884c8 100644 --- a/docs/users_guide/debugging.rst +++ b/docs/users_guide/debugging.rst @@ -63,7 +63,7 @@ Dumping out compiler intermediate structures Dump Template Haskell expressions that we splice in, and what Haskell code the expression evaluates to. - .. ghc-flag:: -dth-dec-file=<file> + .. ghc-flag:: -dth-dec-file=⟨file⟩ Dump expansions of all top-level Template Haskell splices into ⟨file⟩. @@ -282,7 +282,7 @@ Formatting dumps with subexpressions beyond the depth replaced by ellipses. This flag sets the depth. Its default value is 5. -.. ghc-flag:: -dppr-cols=N +.. ghc-flag:: -dppr-cols=⟨n⟩ Set the width of debugging output. Use this if your code is wrapping too much. For example: ``-dppr-cols=200``. @@ -412,8 +412,8 @@ Checking for determinism Set the increment for the generated ``Unique``'s to ⟨i⟩. - This is useful in combination with :ghc-flag:`-dinitial-unique` to test if the - generated files depend on the order of ``Unique``'s. + This is useful in combination with :ghc-flag:`-dinitial-unique=⟨s⟩` to test + if the generated files depend on the order of ``Unique``'s. Some interesting values: diff --git a/docs/users_guide/editing-guide.rst b/docs/users_guide/editing-guide.rst index b8ba081972..cf2ebdd9d3 100644 --- a/docs/users_guide/editing-guide.rst +++ b/docs/users_guide/editing-guide.rst @@ -317,7 +317,7 @@ respectively. For instance, .. code-block:: rest - .. rts-flag:: -C <seconds> + .. rts-flag:: -C ⟨seconds⟩ :default: 20 milliseconds @@ -325,13 +325,28 @@ respectively. For instance, Will be rendered as, - .. rts-flag:: -C <seconds> + .. rts-flag:: -C ⟨seconds⟩ + :noindex: :default: 20 milliseconds Sets the context switch interval to ⟨s⟩ seconds. -and will have an associated index entry generated automatically. +and will have an associated index entry generated automatically. Note that, as +in Style Conventions below, we use ``⟨⟩`` instead of less-than/greater-than +signs. To reference a ``ghc-flag`` or ``rts-flag``, you must match the +definition exactly, including the arguments. A quick way to find the exact +names and special characters is, + +.. code-block:: sh + + $ git grep -- "flag:: -o " + +which will generate the appropriate, + +.. code-block:: none + + separate_compilation.rst:.. ghc-flag:: -o ⟨file⟩ GHCi commands ~~~~~~~~~~~~~ @@ -341,13 +356,14 @@ instance, we can describe the GHCi ``:module`` command, .. code-block:: rest - .. ghci-cmd:: :module [*] <file> + .. ghci-cmd:: :module; [*]⟨file⟩ Load a module which will be rendered as, - .. ghci-cmd:: :module [*] <file> + .. ghci-cmd:: :module; [*]⟨file⟩ + :noindex: Load a module diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst index a7fb53844c..4a3e02e83e 100644 --- a/docs/users_guide/extending_ghc.rst +++ b/docs/users_guide/extending_ghc.rst @@ -190,17 +190,17 @@ restrictions are too onerous, Using compiler plugins ~~~~~~~~~~~~~~~~~~~~~~ -Plugins can be specified on the command line with the :ghc-flag:`-fplugin` -option. ``-fplugin=module`` where ⟨module⟩ is a module in a registered package -that exports a plugin. Arguments can be given to plugins with the -:ghc-flag:`-fplugin-opt` option. +Plugins can be specified on the command line with the +:ghc-flag:`-fplugin=⟨module⟩` option where ⟨module⟩ is a +module in a registered package that exports a plugin. Arguments can be given to +plugins with the :ghc-flag:`-fplugin-opt=⟨module⟩:⟨args⟩` option. -.. ghc-flag:: -fplugin=<module> +.. ghc-flag:: -fplugin=⟨module⟩ - Load the plugin in the given module. The module must be a member of a package - registered in GHC's package database. + Load the plugin in the given module. The module must be a member of a + package registered in GHC's package database. -.. ghc-flag:: -fplugin-opt=<module>:<args> +.. ghc-flag:: -fplugin-opt=⟨module⟩:⟨args⟩ Pass arguments ⟨args⟩ to the given plugin. @@ -228,40 +228,39 @@ control specifically plugin packages: .. ghc-flag:: -plugin-package ⟨pkg⟩ - This option causes the installed package ⟨pkg⟩ to be exposed - for plugins, such as :ghc-flag:`-fplugin`. The - package ⟨pkg⟩ can be specified in full with its version number (e.g. - ``network-1.0``) or the version number can be omitted if there is - only one version of the package installed. If there are multiple - versions of ⟨pkg⟩ installed and :ghc-flag:`-hide-all-plugin-packages` was not - specified, then all other versions will become hidden. :ghc-flag:`-plugin-package` - supports thinning and renaming described in - :ref:`package-thinning-and-renaming`. + This option causes the installed package ⟨pkg⟩ to be exposed for plugins, + such as :ghc-flag:`-fplugin=⟨module⟩`. The package ⟨pkg⟩ can be specified + in full with its version number (e.g. ``network-1.0``) or the version + number can be omitted if there is only one version of the package + installed. If there are multiple versions of ⟨pkg⟩ installed and + :ghc-flag:`-hide-all-plugin-packages` was not specified, then all other + versions will become hidden. :ghc-flag:`-plugin-package ⟨pkg⟩` supports + thinning and renaming described in :ref:`package-thinning-and-renaming`. - Unlike :ghc-flag:`-package`, this option does NOT cause package ⟨pkg⟩ to be linked - into the resulting executable or shared object. + Unlike :ghc-flag:`-package ⟨pkg⟩`, this option does NOT cause package ⟨pkg⟩ + to be linked into the resulting executable or shared object. .. ghc-flag:: -plugin-package-id ⟨pkg-id⟩ - Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package`, but the - package is named by its installed package ID rather than by name. This is a - more robust way to name packages, and can be used to select packages that - would otherwise be shadowed. Cabal passes :ghc-flag:`-plugin-package-id` flags to - GHC. :ghc-flag:`-plugin-package-id` supports thinning and renaming described in - :ref:`package-thinning-and-renaming`. + Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package + ⟨pkg⟩`, but the package is named by its installed package ID rather than by + name. This is a more robust way to name packages, and can be used to + select packages that would otherwise be shadowed. Cabal passes + :ghc-flag:`-plugin-package-id ⟨pkg-id⟩` flags to GHC. + :ghc-flag:`-plugin-package-id ⟨pkg-id⟩` supports thinning and renaming + described in :ref:`package-thinning-and-renaming`. .. ghc-flag:: -hide-all-plugin-packages - By default, all exposed packages in the normal, source import - namespace are also available for plugins. This causes those - packages to be hidden by default. - If you use this flag, then any packages with plugins you require - need to be explicitly exposed using - :ghc-flag:`-plugin-package` options. + By default, all exposed packages in the normal, source import namespace are + also available for plugins. This causes those packages to be hidden by + default. If you use this flag, then any packages with plugins you require + need to be explicitly exposed using :ghc-flag:`-plugin-package ⟨pkg⟩` + options. At the moment, the only way to specify a dependency on a plugin in Cabal is to put it in ``build-depends`` (which uses the conventional -:ghc-flag:`-package-id` flag); however, in the future there +:ghc-flag:`-package-id ⟨unit-id⟩` flag); however, in the future there will be a separate field for specifying plugin dependencies specifically. .. _writing-compiler-plugins: @@ -577,7 +576,7 @@ A frontend plugin allows you to add new major modes to GHC. You may prefer this over a traditional program which calls the GHC API, as GHC manages a lot of parsing flags and administrative nonsense which can be difficult to manage manually. To load a frontend plugin exported by ``Foo.FrontendPlugin``, -we just invoke GHC with the :ghc-flag:`--frontend` flag as follows: +we just invoke GHC with the :ghc-flag:`--frontend ⟨module⟩` flag as follows: .. code-block:: none diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst index 684435cfcc..c40b623800 100644 --- a/docs/users_guide/ffi-chap.rst +++ b/docs/users_guide/ffi-chap.rst @@ -335,12 +335,12 @@ reliably re-initialise after this has happened; see :ref:`infelicities-ffi`. will try to link to the ``Main`` Haskell module. 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` -link-time flag overrides this. However, :ghc-flag:`-rtsopts` has no effect when -:ghc-flag:`-no-hs-main` is in use (and the same goes for :ghc-flag:`-with-rtsopts`). To -set these options we have to call a GHC-specific API instead of -``hs_init()``: +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 +:ghc-flag:`-with-rtsopts=⟨opts⟩`). To set these options we have to call a +GHC-specific API instead of ``hs_init()``: .. code-block:: c @@ -548,7 +548,7 @@ single Haskell thread, and possibly also use a bound thread (see Note that foreign calls made by different Haskell threads may execute in *parallel*, even when the ``+RTS -N`` flag is not being used -(:ref:`parallel-options`). The :rts-flag:`-N` flag controls parallel +(:ref:`parallel-options`). The :rts-flag:`-N ⟨x⟩` flag controls parallel execution of Haskell threads, but there may be an arbitrary number of foreign calls in progress at any one time, regardless of the ``+RTS -N`` value. diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst index 2d27c268b3..8405af163e 100644 --- a/docs/users_guide/ghci.rst +++ b/docs/users_guide/ghci.rst @@ -1133,14 +1133,14 @@ IO ()``, and it works by converting the value to ``String`` using ``show``. This is not ideal in certain cases, like when the output is long, or contains strings with non-ascii characters. -The :ghc-flag:`-interactive-print` flag allows to specify any function of type -``C a => a -> IO ()``, for some constraint ``C``, as the function for -printing evaluated expressions. The function can reside in any loaded -module or any registered package, but only when it resides in a registered -package will it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`, +The :ghc-flag:`-interactive-print ⟨expr⟩` flag allows to specify any function +of type ``C a => a -> IO ()``, for some constraint ``C``, as the function for +printing evaluated expressions. The function can reside in any loaded module or +any registered package, but only when it resides in a registered package will +it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`, :ghci-cmd:`:reload` or, :ghci-cmd:`:set`. -.. ghc-flag:: -interactive-print <expr> +.. ghc-flag:: -interactive-print ⟨expr⟩ Set the function used by GHCi to print evaluation results. Expression must be of type ``C a => a -> IO ()``. @@ -1172,8 +1172,8 @@ will start an interactive session where values with be printed using A custom pretty printing function can be used, for example, to format tree-like and nested structures in a more readable way. -The :ghc-flag:`-interactive-print` flag can also be used when running GHC in -``-e mode``: +The :ghc-flag:`-interactive-print ⟨expr⟩` flag can also be used when running +GHC in ``-e mode``: .. code-block:: none @@ -1729,7 +1729,7 @@ The history is only available when using :ghci-cmd:`:trace`; the reason for this is we found that logging each breakpoint in the history cuts performance by a factor of 2 or more. -.. ghc-flag:: -fghci-hist-size +.. ghc-flag:: -fghci-hist-size=⟨n⟩ :default: 50 @@ -1961,7 +1961,7 @@ to specify any extra flags at all: they will be automatically loaded the first time they are needed. For hidden packages, however, you need to request the package be loaded -by using the :ghc-flag:`-package` flag: +by using the :ghc-flag:`-package ⟨pkg⟩` flag: .. code-block:: none @@ -1999,7 +1999,7 @@ On systems with ``.so``-style shared libraries, the actual library loaded will the ``liblib.so``. GHCi searches the following places for libraries, in this order: -- Paths specified using the :ghc-flag:`-L` command-line option, +- Paths specified using the :ghc-flag:`-L ⟨dir⟩` command-line option, - the standard library search path for your system, which on some systems may be overridden by setting the :envvar:`LD_LIBRARY_PATH` @@ -2321,7 +2321,7 @@ commonly used commands. Display the history of evaluation steps. With a number, displays that many steps (default: 20). For use with :ghci-cmd:`:trace`; see :ref:`tracing`. To set the number of history entries stored by GHCi, - use the :ghc-flag:`-fghci-hist-size` flag. + use the :ghc-flag:`-fghci-hist-size=⟨n⟩` flag. .. ghci-cmd:: :info;[!] ⟨name⟩ @@ -2585,7 +2585,7 @@ commonly used commands. Sets the string to be used as the continuation prompt (used when using the :ghci-cmd:`:{` command) in GHCi. -.. ghci-cmd:: :set prompt-function; <prompt-function> +.. ghci-cmd:: :set prompt-function; ⟨prompt-function⟩ .. index:: single: GHCi prompt function; setting @@ -2598,7 +2598,7 @@ commonly used commands. more information). The second arguments is the line number (as referenced in compiler messages) of the current prompt. -.. ghci-cmd:: :set prompt-cont-function; <prompt-function> +.. ghci-cmd:: :set prompt-cont-function; ⟨prompt-function⟩ Sets the function to be used for the continuation prompt (used when using the :ghci-cmd:`:{` command) displaying in GHCi. @@ -2911,9 +2911,9 @@ option, you can set the reverse option: :ref:`flag-reference` lists the reverse for each option where applicable. -Certain static options (:ghc-flag:`-package`, :ghc-flag:`-I`, :ghc-flag:`-i`, -and :ghc-flag:`-l` in particular) will also work, but some may not take effect -until the next reload. +Certain static options (:ghc-flag:`-package ⟨pkg⟩`, :ghc-flag:`-I⟨dir⟩`, +:ghc-flag:`-i⟨dir⟩[:⟨dir⟩]*`, and :ghc-flag:`-l ⟨lib⟩` in particular) will also +work, but some may not take effect until the next reload. .. index:: single: static; options @@ -3156,8 +3156,8 @@ using messages over a pipe. GHCi debugger, so breakpoints and single-stepping don't work with :ghc-flag:`-fexternal-interpreter`. - See also the :ghc-flag:`-pgmi` (:ref:`replacing-phases`) and :ghc-flag:`-opti` - (:ref:`forcing-options-through`) flags. + See also the :ghc-flag:`-pgmi ⟨cmd⟩` (:ref:`replacing-phases`) and + :ghc-flag:`-opti ⟨option⟩` (:ref:`forcing-options-through`) flags. Why might we want to do this? The main reason is that the RTS running the interpreted code can be a different flavour (profiling or diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst index 79530679b7..78b39924be 100644 --- a/docs/users_guide/glasgow_exts.rst +++ b/docs/users_guide/glasgow_exts.rst @@ -5912,7 +5912,7 @@ Condition (described in :ref:`instance-termination`) are lifted. Termination is still ensured by having a fixed-depth recursion stack. If you exceed the stack depth you get a sort of backtrace, and the opportunity to increase the stack depth with -``-freduction-depth=``\ *N*. However, if you should exceed the default +``-freduction-depth=⟨n⟩``. However, if you should exceed the default reduction depth limit, it is probably best just to disable depth checking, with ``-freduction-depth=0``. The exact depth your program requires depends on minutiae of your code, and it may change between @@ -10033,7 +10033,7 @@ Impredicative polymorphism .. ghc-flag:: -XImpredicativeTypes - :implies: :ghc-flag:`-RankNTypes` + :implies: :ghc-flag:`-XRankNTypes` Allow impredicative polymorphic types. @@ -11124,17 +11124,17 @@ non-trivial program, you may be interested in combining this with the :ghc-flag:`-ddump-to-file` flag (see :ref:`dumping-output`. For each file using Template Haskell, this will show the output in a ``.dump-splices`` file. -The flag :ghc-flag:`-dth-dec-file` shows the expansions of all top-level TH -declaration splices, both typed and untyped, in the file :file:`M.th.hs` -where M is the name of the module being compiled. Note that other types -of splices (expressions, types, and patterns) are not shown. Application -developers can check this into their repository so that they can grep -for identifiers that were defined in Template Haskell. This is similar -to using :ghc-flag:`-ddump-to-file` with :ghc-flag:`-ddump-splices` but it always +The flag :ghc-flag:`-dth-dec-file=⟨file⟩` shows the expansions of all top-level +TH declaration splices, both typed and untyped, in the file :file:`M.th.hs` +where M is the name of the module being compiled. Note that other types of +splices (expressions, types, and patterns) are not shown. Application +developers can check this into their repository so that they can grep for +identifiers that were defined in Template Haskell. This is similar to using +:ghc-flag:`-ddump-to-file` with :ghc-flag:`-ddump-splices` but it always generates a file instead of being coupled to :ghc-flag:`-ddump-to-file`. The -format is also different: it does not show code from the original file, -instead it only shows generated code and has a comment for the splice -location of the original file. +format is also different: it does not show code from the original file, instead +it only shows generated code and has a comment for the splice location of the +original file. Below is a sample output of :ghc-flag:`-ddump-splices` :: @@ -11145,7 +11145,7 @@ Below is a sample output of :ghc-flag:`-ddump-splices` :: foo :: Int -> Int foo x = (x + 1) -Below is the output of the same sample using :ghc-flag:`-dth-dec-file` :: +Below is the output of the same sample using :ghc-flag:`-dth-dec-file=⟨file⟩` :: -- TH_pragma.hs:(6,4)-(8,26): Splicing declarations foo :: Int -> Int @@ -11247,15 +11247,15 @@ Fortunately GHC provides two workarounds. The first option is to compile the program twice: -1. Compile the program or library first the normal way, without :ghc-flag:`-prof`. +1. Compile the program or library first the normal way, without + :ghc-flag:`-prof`. -2. Then compile it again with :ghc-flag:`-prof`, and additionally use ``-osuf p_o`` - to name the object files differently (you can - choose any suffix that isn't the normal object suffix here). GHC will - automatically load the object files built in the first step when - executing splice expressions. If you omit the :ghc-flag:`-osuf` flag when - building with :ghc-flag:`-prof` and Template Haskell is used, GHC will emit - an error message. +2. Then compile it again with :ghc-flag:`-prof`, and additionally use ``-osuf + p_o`` to name the object files differently (you can choose any suffix that + isn't the normal object suffix here). GHC will automatically load the object + files built in the first step when executing splice expressions. If you omit + the :ghc-flag:`-osuf ⟨suffix⟩` flag when building with :ghc-flag:`-prof` and + Template Haskell is used, GHC will emit an error message. .. index:: single : -osuf; using with profiling @@ -13537,7 +13537,7 @@ From a semantic point of view: - Rules are enabled (that is, used during optimisation) by the :ghc-flag:`-fenable-rewrite-rules` flag. This flag is implied by :ghc-flag:`-O`, and may be switched off (as usual) by - :ghc-flag:`-fno-enable-rewrite-rules <-f-enable-rewrite-rules>`. (NB: enabling + :ghc-flag:`-fno-enable-rewrite-rules <-fenable-rewrite-rules>`. (NB: enabling :ghc-flag:`-fenable-rewrite-rules` without :ghc-flag:`-O` may not do what you expect, though, because without :ghc-flag:`-O` GHC ignores all optimisation information in interface files; see :ghc-flag:`-fignore-interface-pragmas`). diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst index 71059f1b9e..3ed9455857 100644 --- a/docs/users_guide/packages.rst +++ b/docs/users_guide/packages.rst @@ -179,21 +179,20 @@ The GHC command line options that control packages are: .. ghc-flag:: -package-id ⟨unit-id⟩ - Exposes a package like :ghc-flag:`-package`, but the package is named by its - unit ID (i.e. the value of ``id`` in its entry in the installed - package database, also previously known as an installed package ID) - rather than by name. This is a more robust way - to name packages, and can be used to select packages that would - otherwise be shadowed. Cabal passes ``-package-id`` flags to GHC. - ``-package-id`` supports thinning and renaming described in - :ref:`package-thinning-and-renaming`. + Exposes a package like :ghc-flag:`-package ⟨pkg⟩`, but the package is named + by its unit ID (i.e. the value of ``id`` in its entry in the installed + package database, also previously known as an installed package ID) rather + than by name. This is a more robust way to name packages, and can be used + to select packages that would otherwise be shadowed. Cabal passes + ``-package-id`` flags to GHC. ``-package-id`` supports thinning and + renaming described in :ref:`package-thinning-and-renaming`. .. ghc-flag:: -hide-all-packages Ignore the exposed flag on installed packages, and hide them all by default. If you use this flag, then any packages you require (including ``base``) need to be explicitly exposed using - :ghc-flag:`-package` options. + :ghc-flag:`-package ⟨pkg⟩` options. This is a good way to insulate your program from differences in the globally exposed packages, and being explicit about package @@ -202,7 +201,7 @@ The GHC command line options that control packages are: .. ghc-flag:: -hide-package ⟨pkg⟩ - This option does the opposite of :ghc-flag:`-package`: it causes the + This option does the opposite of :ghc-flag:`-package ⟨pkg⟩`: it causes the specified package to be hidden, which means that none of its modules will be available for import by Haskell ``import`` directives. @@ -215,11 +214,11 @@ The GHC command line options that control packages are: Causes the compiler to behave as if package ⟨pkg⟩, and any packages that depend on ⟨pkg⟩, are not installed at all. - Saying ``-ignore-package ⟨pkg⟩`` is the same as giving :ghc-flag:`-hide-package` - flags for ⟨pkg⟩ and all the packages that depend on ⟨pkg⟩. Sometimes - we don't know ahead of time which packages will be installed that - depend on ⟨pkg⟩, which is when the :ghc-flag:`-ignore-package` flag can be - useful. + Saying ``-ignore-package ⟨pkg⟩`` is the same as giving + :ghc-flag:`-hide-package ⟨pkg⟩` flags for ⟨pkg⟩ and all the packages that + depend on ⟨pkg⟩. Sometimes we don't know ahead of time which packages will + be installed that depend on ⟨pkg⟩, which is when the + :ghc-flag:`-ignore-package ⟨pkg⟩` flag can be useful. .. ghc-flag:: -no-auto-link-packages @@ -239,26 +238,26 @@ The GHC command line options that control packages are: This option causes the install package ⟨pkg⟩ to be both exposed and trusted by GHC. This command functions in a very similar way - to the :ghc-flag:`-package` command but in addition sets the selected + to the :ghc-flag:`-package ⟨pkg⟩` command but in addition sets the selected packages to be trusted by GHC, regardless of the contents of the package database. (see :ref:`safe-haskell`). .. ghc-flag:: -distrust ⟨pkg⟩ This option causes the install package ⟨pkg⟩ to be both exposed and - distrusted by GHC. This command functions in a very similar - way to the :ghc-flag:`-package` command but in addition sets the selected - packages to be distrusted by GHC, regardless of the contents of the - package database. (see :ref:`safe-haskell`). + distrusted by GHC. This command functions in a very similar way to the + :ghc-flag:`-package ⟨pkg⟩` command but in addition sets the selected + packages to be distrusted by GHC, regardless of the contents of the package + database. (see :ref:`safe-haskell`). .. ghc-flag:: -distrust-all Ignore the trusted flag on installed packages, and distrust them by default. If you use this flag and Safe Haskell then any packages you - require to be trusted (including ``base``) need to be explicitly - trusted using :ghc-flag:`-trust` options. This option does not change the - exposed/hidden status of a package, so it isn't equivalent to - applying :ghc-flag:`-distrust` to all packages on the system. (see + require to be trusted (including ``base``) need to be explicitly trusted + using :ghc-flag:`-trust ⟨pkg⟩` options. This option does not change the + exposed/hidden status of a package, so it isn't equivalent to applying + :ghc-flag:`-distrust ⟨pkg⟩` to all packages on the system. (see :ref:`safe-haskell`). .. _package-main: @@ -266,10 +265,10 @@ The GHC command line options that control packages are: The ``main`` package -------------------- -Every complete Haskell program must define ``main`` in module ``Main`` -in package ``main``. Omitting the :ghc-flag:`-this-unit-id` flag compiles -code for package ``main``. Failure to do so leads to a somewhat obscure -link-time error of the form: +Every complete Haskell program must define ``main`` in module ``Main`` in +package ``main``. Omitting the :ghc-flag:`-this-unit-id ⟨unit-id⟩` flag +compiles code for package ``main``. Failure to do so leads to a somewhat +obscure link-time error of the form: .. code-block:: none @@ -308,8 +307,8 @@ When incorporating packages from multiple sources, you may end up in a situation where multiple packages publish modules with the same name. Previously, the only way to distinguish between these modules was to use :ref:`package-qualified-imports`. However, since GHC 7.10, the -:ghc-flag:`-package` flags (and their variants) have been extended to allow a -user to explicitly control what modules a package brings into scope, by +:ghc-flag:`-package ⟨pkg⟩` flags (and their variants) have been extended to +allow a user to explicitly control what modules a package brings into scope, by analogy to the import lists that users can attach to module imports. The basic syntax is that instead of specifying a package name P to the @@ -375,10 +374,10 @@ stack. Several command line options described below can further manipulate this initial stack. You can see GHC's effective package database stack by running GHC with the :ghc-flag:`-v` flag. -This stack structure means that the order of :ghc-flag:`-package-db` flags or -:envvar:`GHC_PACKAGE_PATH` is important. Each substack of the stack -must be well formed (packages in databases on top of the stack can refer -to packages below, but not vice versa). +This stack structure means that the order of :ghc-flag:`-package-db ⟨file⟩` +flags or :envvar:`GHC_PACKAGE_PATH` is important. Each substack of the stack +must be well formed (packages in databases on top of the stack can refer to +packages below, but not vice versa). *Package shadowing:* When multiple package databases are in use it is possible, though rarely, that the same installed package id is present in @@ -516,8 +515,8 @@ command line arguments to ``ghc``: -package-id id_n Note the implicit :ghc-flag:`-hide-all-packages` and the fact that it is -:ghc-flag:`-package-id`, not :ghc-flag:`-package`. This is because the -environment specifies precisely which packages should be visible. +:ghc-flag:`-package-id ⟨unit-id⟩`, not :ghc-flag:`-package ⟨pkg⟩`. This is +because the environment specifies precisely which packages should be visible. Note that for the ``package-db`` directive, if a relative path is given it must be relative to the location of the package environment file. @@ -530,10 +529,10 @@ must be relative to the location of the package environment file. In order, ``ghc`` will look for the package environment in the following locations: -- File ⟨file⟩ if you pass the option :ghc-flag:`-package-env file`. +- File ⟨file⟩ if you pass the option :ghc-flag:`-package-env ⟨file⟩|⟨name⟩`. - File ``$HOME/.ghc/arch-os-version/environments/name`` if you pass the - option ``-package-env name``. + option ``-package-env ⟨name⟩``. - File ⟨file⟩ if the environment variable ``GHC_ENVIRONMENT`` is set to ⟨file⟩. @@ -667,10 +666,11 @@ Package management (the ``ghc-pkg`` command) single: packages; management The :command:`ghc-pkg` tool is for querying and modifying package databases. To -see what package databases are in use, use ``ghc-pkg list``. The stack -of databases that :command:`ghc-pkg` knows about can be modified using the +see what package databases are in use, use ``ghc-pkg list``. The stack of +databases that :command:`ghc-pkg` knows about can be modified using the :envvar:`GHC_PACKAGE_PATH` environment variable (see :ref:`ghc-package-path`, -and using :ghc-flag:`-package-db` options on the :command:`ghc-pkg` command line. +and using :ghc-flag:`-package-db ⟨file⟩` options on the :command:`ghc-pkg` +command line. When asked to modify a database, ``ghc-pkg`` modifies the global database by default. Specifying ``--user`` causes it to act on the user diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst index f35ba1b272..831ace4a40 100644 --- a/docs/users_guide/phases.rst +++ b/docs/users_guide/phases.rst @@ -161,7 +161,7 @@ Options affecting the C pre-processor large system with significant doses of conditional compilation, you really shouldn't need it. -.. ghc-flag:: -D <symbol>[=<value>] +.. ghc-flag:: -D⟨symbol⟩[=⟨value⟩] Define macro ⟨symbol⟩ in the usual way. NB: does *not* affect ``-D`` macros passed to the C compiler when compiling with :ghc-flag:`-fvia-C`! For @@ -170,11 +170,11 @@ Options affecting the C pre-processor When no value is given, the value is taken to be ``1``. For instance, ``-DUSE_MYLIB`` is equivalent to ``-DUSE_MYLIB=1``. -.. ghc-flag:: -U ⟨symbol⟩ +.. ghc-flag:: -U⟨symbol⟩ Undefine macro ⟨symbol⟩ in the usual way. -.. ghc-flag:: -I ⟨dir⟩ +.. ghc-flag:: -I⟨dir⟩ Specify a directory in which to look for ``#include`` files, in the usual C way. @@ -376,16 +376,16 @@ Options affecting a Haskell pre-processor stripped away and (possibly) the C pre-processor has washed the Haskell input. - Use :ghc-flag:`-pgmF` to select the program to use as the preprocessor. - When invoked, the ⟨cmd⟩ pre-processor is given at least three - arguments on its command-line: the first argument is the name of the - original source file, the second is the name of the file holding the - input, and the third is the name of the file where ⟨cmd⟩ should - write its output to. + Use :ghc-flag:`-pgmF ⟨cmd⟩` to select the program to use as the + preprocessor. When invoked, the ⟨cmd⟩ pre-processor is given at least + three arguments on its command-line: the first argument is the name of the + original source file, the second is the name of the file holding the input, + and the third is the name of the file where ⟨cmd⟩ should write its output + to. Additional arguments to the pre-processor can be passed in using the - :ghc-flag:`-optF` option. These are fed to ⟨cmd⟩ on the command line after - the three standard input and output arguments. + :ghc-flag:`-optF ⟨option⟩` option. These are fed to ⟨cmd⟩ on the command + line after the three standard input and output arguments. An example of a pre-processor is to convert your source files to the input encoding that GHC expects, i.e. create a script ``convert.sh`` @@ -540,12 +540,12 @@ for example). .. ghc-flag:: -staticlib Link all passed files into a static library suitable for linking. - To control the name, use the :ghc-flag:`-o` ⟨name⟩ option + To control the name, use the :ghc-flag:`-o ⟨file⟩` option as usual. The default name is ``liba.a``. .. ghc-flag:: -L ⟨dir⟩ - Where to find user-supplied libraries… Prepend the directory ⟨dir⟩ + Where to f ind user-supplied libraries… Prepend the directory ⟨dir⟩ to the library directories path. .. ghc-flag:: -framework-path ⟨dir⟩ @@ -601,11 +601,11 @@ for example). might be an ELF DSO, a Windows DLL, or a Mac OS dylib. GHC hides the operating system details beneath this uniform flag. - The flags :ghc-flag:`-dynamic` and :ghc-flag:`-static` control whether the resulting - shared object links statically or dynamically to Haskell package - libraries given as :ghc-flag:`-package` option. Non-Haskell libraries are - linked as gcc would regularly link it on your system, e.g. on most - ELF system the linker uses the dynamic libraries when found. + The flags :ghc-flag:`-dynamic` and :ghc-flag:`-static` control whether the + resulting shared object links statically or dynamically to Haskell package + libraries given as :ghc-flag:`-package ⟨pkg⟩` option. Non-Haskell libraries + are linked as gcc would regularly link it on your system, e.g. on most ELF + system the linker uses the dynamic libraries when found. Object files linked into shared objects must be compiled with :ghc-flag:`-fPIC`, see :ref:`options-codegen` @@ -673,11 +673,12 @@ for example). ``Main`` module present (normally the compiler will not attempt linking when there is no ``Main``). - The flags :ghc-flag:`-rtsopts` and :ghc-flag:`-with-rtsopts` have no effect when - used with :ghc-flag:`-no-hs-main`, because they are implemented by changing - the definition of ``main`` that GHC generates. See - :ref:`using-own-main` for how to get the effect of :ghc-flag:`-rtsopts` and - :ghc-flag:`-with-rtsopts` when using your own ``main``. + The flags :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` and + :ghc-flag:`-with-rtsopts=⟨opts⟩` have no effect when used with + :ghc-flag:`-no-hs-main`, because they are implemented by changing the + definition of ``main`` that GHC generates. See :ref:`using-own-main` for + how to get the effect of :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` and + :ghc-flag:`-with-rtsopts=⟨opts⟩` when using your own ``main``. .. ghc-flag:: -debug @@ -699,7 +700,7 @@ for example). The threaded runtime system provides the following benefits: - - It enables the :rts-flag:`-N` RTS option to be used, + - It enables the :rts-flag:`-N ⟨x⟩` RTS option to be used, which allows threads to run in parallelparallelism on a multiprocessormultiprocessorSMP or multicoremulticore machine. See :ref:`using-smp`. @@ -722,7 +723,9 @@ for example). :ghc-flag:`-eventlog` can be used with :ghc-flag:`-threaded`. It is implied by :ghc-flag:`-debug`. -.. ghc-flag:: -rtsopts +.. ghc-flag:: -rtsopts[=⟨none|some|all⟩] + + :default: all This option affects the processing of RTS control options given either on the command line or via the :envvar:`GHCRTS` environment @@ -754,7 +757,7 @@ for example). Note that ``-rtsopts`` has no effect when used with :ghc-flag:`-no-hs-main`; see :ref:`using-own-main` for details. -.. ghc-flag:: -with-rtsopts +.. ghc-flag:: -with-rtsopts=⟨opts⟩ This option allows you to set the default RTS options at link-time. For example, ``-with-rtsopts="-H128m"`` sets the default heap size @@ -769,12 +772,12 @@ for example). .. ghc-flag:: -no-rtsopts-suggestions - This option disables RTS suggestions about linking with :ghc-flag:`-rtsopts` - when they are not available. These suggestions would be unhelpful if - the users have installed Haskell programs through their package - managers. With this option enabled, these suggestions will not - appear. It is recommended for people distributing binaries to build - with either ``-rtsopts`` or ``-no-rtsopts-suggestions``. + This option disables RTS suggestions about linking with + :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` when they are not available. These + suggestions would be unhelpful if the users have installed Haskell programs + through their package managers. With this option enabled, these suggestions + will not appear. It is recommended for people distributing binaries to + build with either ``-rtsopts`` or ``-no-rtsopts-suggestions``. .. ghc-flag:: -fno-gen-manifest @@ -812,16 +815,15 @@ for example). .. index:: single: windres - The manifest file that GHC generates when linking a binary on - Windows is also embedded in the executable itself, by default. This - means that the binary can be distributed without having to supply - the manifest file too. The embedding is done by running - :command:`windres`; to see exactly what GHC does to embed the - manifest, use the :ghc-flag:`-v` flag. A GHC installation comes with its own - copy of ``windres`` for this reason. + The manifest file that GHC generates when linking a binary on Windows is + also embedded in the executable itself, by default. This means that the + binary can be distributed without having to supply the manifest file too. + The embedding is done by running :command:`windres`; to see exactly what + GHC does to embed the manifest, use the :ghc-flag:`-v` flag. A GHC + installation comes with its own copy of ``windres`` for this reason. - See also :ghc-flag:`-pgmwindres` (:ref:`replacing-phases`) and - :ghc-flag:`-optwindres` (:ref:`forcing-options-through`). + See also :ghc-flag:`-pgmwindres ⟨cmd⟩` (:ref:`replacing-phases`) and + :ghc-flag:`-optwindres ⟨option⟩` (:ref:`forcing-options-through`). .. ghc-flag:: -fno-shared-implib @@ -838,7 +840,7 @@ for example). :ghc-flag:`-fno-shared-implib` flag to disable the creation of the import library entirely. -.. ghc-flag:: -dylib-install-name <path> +.. ghc-flag:: -dylib-install-name ⟨path⟩ On Darwin/OS X, dynamic libraries are stamped at build time with an "install name", which is the ultimate install path of the library diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst index cf345ed513..0a4ba09fe2 100644 --- a/docs/users_guide/profiling.rst +++ b/docs/users_guide/profiling.rst @@ -402,8 +402,9 @@ enclosed between ``+RTS ... -RTS`` as usual): single: time profile The :rts-flag:`-p` option produces a standard *time profile* report. It is - written into the file :file:`<stem>.prof`; the stem is taken to be the program - name by default, but can be overridden by the :rts-flag:`-po` flag. + written into the file :file:`<stem>.prof`; the stem is taken to be the + program name by default, but can be overridden by the :rts-flag:`-po + ⟨stem⟩` flag. The :rts-flag:`-P` option produces a more detailed report containing the actual time and allocation data as well. (Not used much.) @@ -418,19 +419,36 @@ enclosed between ``+RTS ... -RTS`` as usual): .. rts-flag:: -po ⟨stem⟩ - The :rts-flag:`-po` option overrides the stem used to form the output file - paths for the cost-centre profiler (see :rts-flag:`-p` and :rts-flag:`-pj` - flags above) and heap profiler (see :rts-flag:`-h`). + The :rts-flag:`-po ⟨stem⟩` option overrides the stem used to form the + output file paths for the cost-centre profiler (see :rts-flag:`-p` and + :rts-flag:`-pj` flags above) and heap profiler (see :rts-flag:`-h`). For instance, running a program with ``+RTS -h -p -pohello-world`` would produce a heap profile named :file:`hello-world.hp` and a cost-centre profile named :file:`hello-world.prof`. -.. rts-flag:: -V <secs> +.. rts-flag:: -V ⟨secs⟩ + + Sets the interval that the RTS clock ticks at, which is also the sampling + interval of the time and allocation profile. The default is 0.02 seconds. + The runtime uses a single timer signal to count ticks; this timer signal is + used to control the context switch timer (:ref:`using-concurrent`) and the + heap profiling timer :ref:`rts-options-heap-prof`. Also, the time profiler + uses the RTS timer signal directly to record time profiling samples. + + Normally, setting the :rts-flag:`-V ⟨secs⟩` option directly is not + necessary: the resolution of the RTS timer is adjusted automatically if a + short interval is requested with the :rts-flag:`-C ⟨s⟩` or :rts-flag:`-i + ⟨secs⟩` options. However, setting :rts-flag:`-V ⟨secs⟩` is required in + order to increase the resolution of the time profiler. + + Using a value of zero disables the RTS clock completely, and has the + effect of disabling timers that depend on it: the context switch + timer and the heap profiling timer. Context switches will still + happen, but deterministically and at a rate much faster than normal. + Disabling the interval timer is useful for debugging, because it + eliminates a source of non-determinism at runtime. - Sets the interval that the RTS clock ticks at, which is also the - sampling interval of the time and allocation profile. The default is - 0.02 seconds. .. rts-flag:: -xc @@ -456,7 +474,7 @@ has the following properties, The command line arguments passed to the runtime system ``initial_capabilities`` (integral number) How many capabilities the program was started with (e.g. using the - :rts-flag:`-N` option). Note that the number of capabilities may change + :rts-flag:`-N ⟨x⟩` option). Note that the number of capabilities may change during execution due to the ``setNumCapabilities`` function. ``total_time`` (number) The total wall time of the program's execution in seconds. @@ -694,42 +712,42 @@ follows: The flags below are marked with ``:noindex:`` to avoid duplicate ID warnings from Sphinx. -.. rts-flag:: -hc <name> +.. rts-flag:: -hc ⟨name⟩ :noindex: Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres at the top. -.. rts-flag:: -hC <name> +.. rts-flag:: -hC ⟨name⟩ :noindex: Restrict the profile to closures produced by cost-centre stacks with one of the specified cost centres anywhere in the stack. -.. rts-flag:: -hm <module> +.. rts-flag:: -hm ⟨module⟩ :noindex: Restrict the profile to closures produced by the specified modules. -.. rts-flag:: -hd <desc> +.. rts-flag:: -hd ⟨desc⟩ :noindex: Restrict the profile to closures with the specified description strings. -.. rts-flag:: -hy <type> +.. rts-flag:: -hy ⟨type⟩ :noindex: Restrict the profile to closures with the specified types. -.. rts-flag:: -hr <cc> +.. rts-flag:: -hr ⟨cc⟩ :noindex: Restrict the profile to closures with retainer sets containing cost-centre stacks with one of the specified cost centres at the top. -.. rts-flag:: -hb <bio> +.. rts-flag:: -hb ⟨bio⟩ :noindex: Restrict the profile to closures with one of the specified @@ -750,7 +768,7 @@ doesn't currently support mixing the :rts-flag:`-hr` and :rts-flag:`-hb` options There are three more options which relate to heap profiling: -.. rts-flag:: -i <secs> +.. rts-flag:: -i ⟨secs⟩ Set the profiling (sampling) interval to ⟨secs⟩ seconds (the default is 0.1 second). Fractions are allowed: for example ``-i0.2`` will @@ -772,7 +790,7 @@ There are three more options which relate to heap profiling: “STACK” respectively when displaying the profile by closure description or type description. -.. rts-flag:: -L <num> +.. rts-flag:: -L ⟨num⟩ Sets the maximum length of a cost-centre stack name in a heap profile. Defaults to 25. @@ -809,9 +827,9 @@ to discover the full retainer set for each object, which can be quite slow. So we set a limit on the maximum size of a retainer set, where all retainer sets larger than the maximum retainer set size are replaced by the special set ``MANY``. The maximum set size defaults to 8 and can be -altered with the :rts-flag:`-R` RTS option: +altered with the :rts-flag:`-R ⟨size⟩` RTS option: -.. rts-flag:: -R <size> +.. rts-flag:: -R ⟨size⟩ Restrict the number of elements in a retainer set to ⟨size⟩ (default 8). @@ -909,17 +927,16 @@ reasons for this: currently 2 extra words per heap object, which probably results in about a 30% overhead. -- Garbage collection requires more memory than the actual residency. - The factor depends on the kind of garbage collection algorithm in - use: a major GC in the standard generation copying collector will - usually require 3L bytes of memory, where L is the amount of live - data. This is because by default (see the RTS :rts-flag:`-F` option) we - allow the old generation to grow to twice its size (2L) before - collecting it, and we require additionally L bytes to copy the live - data into. When using compacting collection (see the :rts-flag:`-c` - option), this is reduced to 2L, and can further be reduced by - tweaking the :rts-flag:`-F` option. Also add the size of the allocation area - (see :rts-flag:`-A`). +- Garbage collection requires more memory than the actual residency. The + factor depends on the kind of garbage collection algorithm in use: a major GC + in the standard generation copying collector will usually require 3L bytes of + memory, where L is the amount of live data. This is because by default (see + the RTS :rts-flag:`-F ⟨factor⟩` option) we allow the old generation to grow + to twice its size (2L) before collecting it, and we require additionally L + bytes to copy the live data into. When using compacting collection (see the + :rts-flag:`-c` option), this is reduced to 2L, and can further be reduced by + tweaking the :rts-flag:`-F ⟨factor⟩` option. Also add the size of the + allocation area (see :rts-flag:`-A ⟨size⟩`). - The stack isn't counted in the heap profile by default. See the RTS :rts-flag:`-xt` option. @@ -976,7 +993,7 @@ The flags are: to use a big box instead. The ``-b`` option forces ``hp2ps`` to use a big box. -.. option:: -e<float>[in|mm|pt] +.. option:: -e⟨float⟩[in|mm|pt] Generate encapsulated PostScript suitable for inclusion in LaTeX documents. Usually, the PostScript graph is drawn in landscape mode @@ -1004,7 +1021,7 @@ The flags are: necessary. No key is produced as it won't fit!. It is useful for creation time profiles with many bands. -.. option:: -m<int> +.. option:: -m⟨int⟩ Normally a profile is limited to 20 bands with additional identifiers being grouped into an ``OTHER`` band. The ``-m`` flag @@ -1029,7 +1046,7 @@ The flags are: Use a small box for the title. -.. option:: -t<float> +.. option:: -t⟨float⟩ Normally trace elements which sum to a total of less than 1% of the profile are removed from the profile. The ``-t`` option allows this @@ -1174,7 +1191,7 @@ Profiling Parallel and Concurrent Programs Combining :ghc-flag:`-threaded` and :ghc-flag:`-prof` is perfectly fine, and indeed it is possible to profile a program running on multiple processors with -the RTS :rts-flag:`-N` option. [3]_ +the RTS :rts-flag:`-N ⟨x⟩` option. [3]_ Some caveats apply, however. In the current implementation, a profiled program is likely to scale much less well than the unprofiled program, diff --git a/docs/users_guide/runtime_control.rst b/docs/users_guide/runtime_control.rst index 3c606c92bf..5286784809 100644 --- a/docs/users_guide/runtime_control.rst +++ b/docs/users_guide/runtime_control.rst @@ -32,7 +32,7 @@ There are four ways to set RTS options: - on the command line between ``+RTS ... -RTS``, when running the program (:ref:`rts-opts-cmdline`) -- at compile-time, using :ghc-flag:`-with-rtsopts` +- at compile-time, using :ghc-flag:`-with-rtsopts=⟨opts⟩` (:ref:`rts-opts-compile-time`) - with the environment variable :envvar:`GHCRTS` @@ -50,9 +50,9 @@ Setting RTS options on the command line single: -RTS single: --RTS -If you set the :ghc-flag:`-rtsopts` 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⟩]` 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: @@ -211,29 +211,7 @@ is written through a custom `EventLogWriter`: Miscellaneous RTS options ------------------------- -.. rts-flag:: -V <secs> - - Sets the interval that the RTS clock ticks at. The runtime uses a - single timer signal to count ticks; this timer signal is used to - control the context switch timer (:ref:`using-concurrent`) and the - heap profiling timer :ref:`rts-options-heap-prof`. Also, the time - profiler uses the RTS timer signal directly to record time profiling - samples. - - Normally, setting the :rts-flag:`-V` option directly is not necessary: the - resolution of the RTS timer is adjusted automatically if a short interval is - requested with the :rts-flag:`-C` or :rts-flag:`-i` options. However, - setting :rts-flag:`-V` is required in order to increase the resolution of - the time profiler. - - Using a value of zero disables the RTS clock completely, and has the - effect of disabling timers that depend on it: the context switch - timer and the heap profiling timer. Context switches will still - happen, but deterministically and at a rate much faster than normal. - Disabling the interval timer is useful for debugging, because it - eliminates a source of non-determinism at runtime. - -.. rts-flag:: --install-signal-handlers=<yes|no> +.. rts-flag:: --install-signal-handlers=⟨yes|no⟩ If yes (the default), the RTS installs signal handlers to catch things like ctrl-C. This option is primarily useful for when you are @@ -246,7 +224,7 @@ Miscellaneous RTS options capabilities. To disable the timer signal, use the ``-V0`` RTS option (see above). -.. rts-flag:: -xm <address> +.. rts-flag:: -xm ⟨address⟩ .. index:: single: -xm; RTS option @@ -268,14 +246,14 @@ Miscellaneous RTS options support for allocating memory in the low 2Gb if available (e.g. ``mmap`` with ``MAP_32BIT`` on Linux), or otherwise ``-xm40000000``. -.. rts-flag:: -xq <size> +.. rts-flag:: -xq ⟨size⟩ :default: 100k This option relates to allocation limits; for more about this see :base-ref:`enableAllocationLimit <GHC-Conc.html#v%3AenableAllocationLimit>`. When a thread hits its allocation limit, the RTS throws an exception - to the thread, and the thread gets an additional quota of allocation + to the thread, and the thread gets an additional quota of allo before the exception is raised again, the idea being so that the thread can execute its exception handlers. The ``-xq`` controls the size of this additional quota. @@ -303,16 +281,16 @@ performance. Set the allocation area size used by the garbage collector. The allocation area (actually generation 0 step 0) is - fixed and is never resized (unless you use :rts-flag:`-H`, below). + fixed and is never resized (unless you use :rts-flag:`-H [⟨size⟩]`, below). Increasing the allocation area size may or may not give better performance (a bigger allocation area means worse cache behaviour but fewer garbage collections and less promotion). - With only 1 generation (e.g. ``-G1``, see :rts-flag:`-G`) the ``-A`` option - specifies the minimum allocation area, since the actual size of the - allocation area will be resized according to the amount of data in the heap - (see :rts-flag:`-F`, below). + With only 1 generation (e.g. ``-G1``, see :rts-flag:`-G ⟨generations⟩`) the + ``-A`` option specifies the minimum allocation area, since the actual size + of the allocation area will be resized according to the amount of data in + the heap (see :rts-flag:`-F ⟨factor⟩`, below). .. rts-flag:: -AL ⟨size⟩ @@ -349,10 +327,10 @@ performance. .. index:: single: old generation, size - Set the minimum size of the old generation. The old - generation is collected whenever it grows to this size or the value - of the :rts-flag:`-F` option multiplied by the size of the live data at the - previous major collection, whichever is larger. + Set the minimum size of the old generation. The old generation is collected + whenever it grows to this size or the value of the :rts-flag:`-F ⟨factor⟩` + option multiplied by the size of the live data at the previous major + collection, whichever is larger. .. rts-flag:: -n ⟨size⟩ @@ -395,8 +373,8 @@ 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` option), compaction can in - fact reduce the GC cost by allowing fewer GCs to be performed. This + 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%. @@ -409,11 +387,10 @@ performance. :default: 30 - Automatically enable compacting collection when the - live data exceeds ⟨n⟩% of the maximum heap size (see the :rts-flag:`-M` - option). Note that the maximum heap size is unlimited by default, so - this option has no effect unless the maximum heap size is set with - ``-M ⟨size⟩.`` + Automatically enable compacting collection when the live data exceeds ⟨n⟩% + of the maximum heap size (see the :rts-flag:`-M ⟨size⟩` option). Note that + the maximum heap size is unlimited by default, so this option has no effect + unless the maximum heap size is set with ``-M ⟨size⟩.`` .. rts-flag:: -F ⟨factor⟩ @@ -429,13 +406,13 @@ performance. when we last collected it, then by default we'll wait until it grows to 4M before collecting it again. - The default seems to work well here. If you have plenty of memory, - it is usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H`) than to + The default seems to work well here. If you have plenty of memory, it is + usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H [⟨size⟩]`) than to increase ``-F ⟨factor⟩.`` - The ``-F`` setting will be automatically reduced by the garbage + The ``-F ⟨factor⟩`` setting will be automatically reduced by the garbage collector when the maximum heap size (the ``-M ⟨size⟩`` setting, see - :rts-flag:`-M`) is approaching. + :rts-flag:`-M ⟨size⟩`) is approaching. .. rts-flag:: -G ⟨generations⟩ @@ -452,13 +429,13 @@ performance. get collected. Specifying 1 generation with ``+RTS -G1`` gives you a simple 2-space - collector, as you would expect. In a 2-space collector, the :rts-flag:`-A` - option specifies the *minimum* allocation area size, since the allocation - area will grow with the amount of live data in the heap. In a - multi-generational collector the allocation area is a fixed size (unless you - use the :rts-flag:`-H` option). + collector, as you would expect. In a 2-space collector, the :rts-flag:`-A + ⟨size⟩` option specifies the *minimum* allocation area size, since the + allocation area will grow with the amount of live data in the heap. In a + multi-generational collector the allocation area is a fixed size (unless + you use the :rts-flag:`-H [⟨size⟩]` option). -.. rts-flag:: -qg <gen> +.. rts-flag:: -qg ⟨gen⟩ :default: 0 :since: 6.12.1 @@ -466,17 +443,16 @@ performance. Use parallel GC in generation ⟨gen⟩ and higher. Omitting ⟨gen⟩ turns off the parallel GC completely, reverting to sequential GC. - The default parallel GC settings are usually suitable for parallel - programs (i.e. those using ``par``, Strategies, or with multiple - threads). However, it is sometimes beneficial to enable the parallel - GC for a single-threaded sequential program too, especially if the - program has a large amount of heap data and GC is a significant - fraction of runtime. To use the parallel GC in a sequential program, - enable the parallel runtime with a suitable :rts-flag:`-N` option, and - additionally it might be beneficial to restrict parallel GC to the - old generation with ``-qg1``. + The default parallel GC settings are usually suitable for parallel programs + (i.e. those using ``par``, Strategies, or with multiple threads). However, + it is sometimes beneficial to enable the parallel GC for a single-threaded + sequential program too, especially if the program has a large amount of + heap data and GC is a significant fraction of runtime. To use the parallel + GC in a sequential program, enable the parallel runtime with a suitable + :rts-flag:`-N ⟨x⟩` option, and additionally it might be beneficial to + restrict parallel GC to the old generation with ``-qg1``. -.. rts-flag:: -qb <gen> +.. rts-flag:: -qb ⟨gen⟩ :default: 1 for ``-A`` < 32M, 0 otherwise :since: 6.12.1 @@ -494,7 +470,7 @@ performance. program it is sometimes beneficial to disable load-balancing entirely with ``-qb``. -.. rts-flag:: -qn <x> +.. rts-flag:: -qn ⟨x⟩ :default: the value of ``-N`` or the number of CPU cores, whichever is smaller. @@ -526,10 +502,10 @@ performance. .. index:: single: heap size, suggested - This option provides a "suggested heap size" for the - garbage collector. Think of ``-Hsize`` as a variable :rts-flag:`-A` option. - It says: I want to use at least ⟨size⟩ bytes, so use whatever is - left over to increase the ``-A`` value. + This option provides a "suggested heap size" for the garbage collector. + Think of ``-Hsize`` as a variable :rts-flag:`-A ⟨size⟩` option. It says: I + want to use at least ⟨size⟩ bytes, so use whatever is left over to increase + the ``-A`` value. This option does not put a *limit* on the heap size: the heap may grow beyond the given size as usual. @@ -597,18 +573,17 @@ performance. .. index:: single: stack; chunk size - Set the size of "stack chunks". When a thread's - current stack overflows, a new stack chunk is created and added to - the thread's stack, until the limit set by :rts-flag:`-K` is reached. + Set the size of "stack chunks". When a thread's current stack overflows, a + new stack chunk is created and added to the thread's stack, until the limit + set by :rts-flag:`-K ⟨size⟩` is reached. - The advantage of smaller stack chunks is that the garbage collector - can avoid traversing stack chunks if they are known to be unmodified - since the last collection, so reducing the chunk size means that the - garbage collector can identify more stack as unmodified, and the GC - overhead might be reduced. On the other hand, making stack chunks - too small adds some overhead as there will be more - overflow/underflow between chunks. The default setting of 32k - appears to be a reasonable compromise in most cases. + The advantage of smaller stack chunks is that the garbage collector can + avoid traversing stack chunks if they are known to be unmodified since the + last collection, so reducing the chunk size means that the garbage + collector can identify more stack as unmodified, and the GC overhead might + be reduced. On the other hand, making stack chunks too small adds some + overhead as there will be more overflow/underflow between chunks. The + default setting of 32k appears to be a reasonable compromise in most cases. .. rts-flag:: -kb ⟨size⟩ @@ -623,10 +598,10 @@ performance. immediate underflow and repeated overflow/underflow at the boundary. The amount of stack moved is set by the ``-kb`` option. - Note that to avoid wasting space, this value should typically be - less than 10% of the size of a stack chunk (:rts-flag:`-kc`), because in a - chain of stack chunks, each chunk will have a gap of unused space of - this size. + Note that to avoid wasting space, this value should typically be less than + 10% of the size of a stack chunk (:rts-flag:`-kc ⟨size⟩`), because in a + chain of stack chunks, each chunk will have a gap of unused space of this + size. .. rts-flag:: -K ⟨size⟩ @@ -680,7 +655,7 @@ performance. .. index:: single: heap size, grace - If the program's heap exceeds the value set by :rts-flag:`-M`, the + If the program's heap exceeds the value set by :rts-flag:`-M ⟨size⟩`, the RTS throws an exception to the program, and the program gets an additional quota of allocation before the exception is raised again, the idea being so that the program can execute its @@ -743,9 +718,9 @@ RTS options to produce runtime statistics ----------------------------------------- .. rts-flag:: -T - -t [<file>] - -s [<file>] - -S [<file>] + -t [⟨file⟩] + -s [⟨file⟩] + -S [⟨file⟩] --machine-readable These options produce runtime-system statistics, such as the amount @@ -950,7 +925,7 @@ executables: ``THUNK``). To get a more detailed profile, use the full profiling support (:ref:`profiling`). Can be shortened to ``-h``. -.. rts-flag:: -L <n> +.. rts-flag:: -L ⟨n⟩ :default: 25 characters @@ -980,7 +955,7 @@ When the program is linked with the :ghc-flag:`-eventlog` option - As text to standard output, for debugging purposes. -.. rts-flag:: -l <flags> +.. rts-flag:: -l ⟨flags⟩ Log events in binary format. Without any ⟨flags⟩ specified, this logs a default set of events, suitable for use with tools like ThreadScope. @@ -1091,7 +1066,7 @@ recommended for everyday use! Produce "ticky-ticky" statistics at the end of the program run (only available if the program was linked with :ghc-flag:`-debug`). The ⟨file⟩ - business works just like on the :rts-flag:`-S` RTS option, above. + business works just like on the :rts-flag:`-S [⟨file⟩]` RTS option, above. For more information on ticky-ticky profiling, see :ref:`ticky-ticky`. diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst index 0c981d5775..04ef591af6 100644 --- a/docs/users_guide/separate_compilation.rst +++ b/docs/users_guide/separate_compilation.rst @@ -65,12 +65,12 @@ an object file, and an interface file. The object file, which normally ends in a ``.o`` suffix, contains the compiled code for the module. -The interface file, which normally ends in a ``.hi`` suffix, contains -the information that GHC needs in order to compile further modules that -depend on this module. It contains things like the types of exported -functions, definitions of data types, and so on. It is stored in a -binary format, so don't try to read one; use the :ghc-flag:`--show-iface` option -instead (see :ref:`hi-options`). +The interface file, which normally ends in a ``.hi`` suffix, contains the +information that GHC needs in order to compile further modules that depend on +this module. It contains things like the types of exported functions, +definitions of data types, and so on. It is stored in a binary format, so don't +try to read one; use the :ghc-flag:`--show-iface ⟨file⟩` option instead (see +:ref:`hi-options`). You should think of the object file and the interface file as a pair, since the interface file is in a sense a compiler-readable description @@ -97,10 +97,10 @@ changed with the ``-osuf`` option). by slashes. GHC will silently create the necessary directory structure underneath ⟨dir⟩, if it does not already exist. -The name of the interface file is derived using the same rules, except -that the suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and -the relevant options are :ghc-flag:`-hidir` and :ghc-flag:`-hisuf` instead of -:ghc-flag:`-odir` and :ghc-flag:`-osuf` respectively. +The name of the interface file is derived using the same rules, except that the +suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and the relevant +options are :ghc-flag:`-hidir ⟨dir⟩` and :ghc-flag:`-hisuf ⟨suffix⟩` instead of +:ghc-flag:`-odir ⟨dir⟩` and :ghc-flag:`-osuf ⟨suffix⟩` respectively. For example, if GHC compiles the module ``A.B.C`` in the file ``src/A/B/C.hs``, with no ``-odir`` or ``-hidir`` flags, the interface @@ -119,9 +119,9 @@ for the interface for module ``Main`` (because it is never imported). It is therefore possible to have several ``Main`` modules in separate source files in the same directory, and GHC will not get confused. -In batch compilation mode, the name of the object file can also be -overridden using the :ghc-flag:`-o` option, and the name of the interface file -can be specified directly using the :ghc-flag:`-ohi` option. +In batch compilation mode, the name of the object file can also be overridden +using the :ghc-flag:`-o ⟨file⟩` option, and the name of the interface file can +be specified directly using the :ghc-flag:`-ohi ⟨file⟩` option. .. _search-path: @@ -286,7 +286,8 @@ Redirecting the compilation output(s) .. ghc-flag:: -outputdir ⟨dir⟩ The ``-outputdir`` option is shorthand for the combination of - :ghc-flag:`-odir`, :ghc-flag:`-hidir`, :ghc-flag:`-stubdir` and :ghc-flag:`-dumpdir`. + :ghc-flag:`-odir ⟨dir⟩`, :ghc-flag:`-hidir ⟨dir⟩`, :ghc-flag:`-stubdir + ⟨dir⟩` and :ghc-flag:`-dumpdir ⟨dir⟩`. .. ghc-flag:: -osuf ⟨suffix⟩ -hisuf ⟨suffix⟩ @@ -390,11 +391,11 @@ Redirecting temporary files .. index:: single: temporary files; redirecting -.. ghc-flag:: -tmpdir +.. ghc-flag:: -tmpdir ⟨dir⟩ If you have trouble because of running out of space in ``/tmp`` (or wherever your installation thinks temporary files should go), you - may use the ``-tmpdir <dir>``-tmpdir <dir> option option to specify an + may use the :ghc-flag:`-tmpdir ⟨dir⟩` option option to specify an alternate directory. For example, ``-tmpdir .`` says to put temporary files in the current working directory. @@ -430,7 +431,7 @@ Other options related to interface files Dump to the file :file:`{M}.imports` (where ⟨M⟩ is the name of the module being compiled) a "minimal" set of import declarations. The directory where the ``.imports`` files are created can be controlled - via the :ghc-flag:`-dumpdir` option. + via the :ghc-flag:`-dumpdir ⟨dir⟩` option. You can safely replace all the import declarations in :file:`{M}.hs` with those found in its respective ``.imports`` file. Why would you want @@ -732,7 +733,7 @@ to ``hs-boot`` files, but with some slight changes: - Unlike regular modules, the defined entities of a signature include not only those written in the local ``hsig`` file, but also those from inherited signatures - (as inferred from the :ghc-flag:`-package-id` flags). + (as inferred from the :ghc-flag:`-package-id ⟨unit-id⟩` flags). These entities are not considered in scope when typechecking the local ``hsig`` file, but are available for import by any module or signature which imports the signature. The @@ -1186,7 +1187,7 @@ generation are: ``.depend`` and then ``include`` the file ``.depend`` into ``Makefile``. -.. ghc-flag:: -dep-suffix <suf> +.. ghc-flag:: -dep-suffix ⟨suffix⟩ Make dependencies that declare that files with suffix ``.<suf><osuf>`` depend on interface files with suffix @@ -1197,7 +1198,7 @@ generation are: Note that you must provide at least one suffix; if you do not want a suffix then pass ``-dep-suffix ''``. -.. ghc-flag:: --exclude-module=<file> +.. ghc-flag:: --exclude-module=⟨file⟩ Regard ``<file>`` as "stable"; i.e., exclude it from having dependencies on it. @@ -1296,10 +1297,9 @@ creating an orphan module. Like any warning, you can switch the warning off with :ghc-flag:`-Wno-orphans <-Worphans>`, and :ghc-flag:`-Werror` will make the compilation fail if the warning is issued. -You can identify an orphan module by looking in its interface file, -``M.hi``, using the :ghc-flag:`--show-iface` :ref:`mode <modes>`. If there is a -``[orphan module]`` on the first line, GHC considers it an orphan -module. +You can identify an orphan module by looking in its interface file, ``M.hi``, +using the :ghc-flag:`--show-iface ⟨file⟩` :ref:`mode <modes>`. If there is a +``[orphan module]`` on the first line, GHC considers it an orphan module. .. [1] This is a change in behaviour relative to 6.2 and earlier. diff --git a/docs/users_guide/shared_libs.rst b/docs/users_guide/shared_libs.rst index c0c54f1e9d..486df51ad9 100644 --- a/docs/users_guide/shared_libs.rst +++ b/docs/users_guide/shared_libs.rst @@ -212,14 +212,13 @@ paths. The unix tool ``readelf --dynamic`` is handy for inspecting the Mac OS X ~~~~~~~~ -The standard assumption on Darwin/Mac OS X is that dynamic libraries -will be stamped at build time with an "install name", which is the full -ultimate install path of the library file. Any libraries or executables -that subsequently link against it (even if it hasn't been installed yet) -will pick up that path as their runtime search location for it. When -compiling with ghc directly, the install name is set by default to the -location where it is built. You can override this with the -:ghc-flag:`-dylib-install-name` option (which passes ``-install_name`` to the -Apple linker). Cabal does this for you. It automatically sets the -install name for dynamic libraries to the absolute path of the ultimate -install location. +The standard assumption on Darwin/Mac OS X is that dynamic libraries will be +stamped at build time with an "install name", which is the full ultimate +install path of the library file. Any libraries or executables that +subsequently link against it (even if it hasn't been installed yet) will pick +up that path as their runtime search location for it. When compiling with ghc +directly, the install name is set by default to the location where it is built. +You can override this with the :ghc-flag:`-dylib-install-name ⟨path⟩` option +(which passes ``-install_name`` to the Apple linker). Cabal does this for you. +It automatically sets the install name for dynamic libraries to the absolute +path of the ultimate install location. diff --git a/docs/users_guide/sooner.rst b/docs/users_guide/sooner.rst index 48958d67c8..6851536cfb 100644 --- a/docs/users_guide/sooner.rst +++ b/docs/users_guide/sooner.rst @@ -30,11 +30,11 @@ Use more memory: .. index:: 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`) 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`). + 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⟩`). .. index:: single: -A⟨size⟩; RTS option @@ -114,13 +114,13 @@ Optimise, using ``-O`` or ``-O2``: Compile via LLVM: The :ref:`LLVM code generator <llvm-code-gen>` can sometimes do a far - better job at producing fast code than the :ref:`native code - generator <native-code-gen>`. This is not universal and depends - on the code. Numeric heavy code seems to show the best improvement - when compiled via LLVM. You can also experiment with passing - specific flags to LLVM with the :ghc-flag:`-optlo` and :ghc-flag:`-optlc` - flags. Be careful though as setting these flags stops GHC from setting its - usual flags for the LLVM optimiser and compiler. + better job at producing fast code than the :ref:`native code generator + <native-code-gen>`. This is not universal and depends on the code. Numeric + heavy code seems to show the best improvement when compiled via LLVM. You + can also experiment with passing specific flags to LLVM with the + :ghc-flag:`-optlo ⟨option⟩` and :ghc-flag:`-optlc ⟨option⟩` flags. Be + careful though as setting these flags stops GHC from setting its usual + flags for the LLVM optimiser and compiler. Overloaded functions are not your friend: Haskell's overloading (using type classes) is elegant, neat, etc., @@ -149,7 +149,7 @@ Use ``SPECIALIZE`` pragmas: "But how do I know where overloading is creeping in?" A low-tech way: grep (search) your interface files for overloaded type signatures. You can view interface files using the - :ghc-flag:`--show-iface` option (see :ref:`hi-options`). + :ghc-flag:`--show-iface ⟨file⟩` option (see :ref:`hi-options`). .. code-block:: sh @@ -303,13 +303,13 @@ Use unboxed arrays (``UArray``) ``Data.Array`` library. Use a bigger heap! - If your program's GC stats (:rts-flag:`-S` RTS option) indicate that - it's doing lots of garbage-collection (say, more than 20% of execution + 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 ``-H⟨size⟩`` or ``-A⟨size⟩`` RTS options (see :ref:`rts-options-gc`). As a rule of thumb, try setting ``-H⟨size⟩`` to the amount of memory you're willing to let your process - consume, or perhaps try passing :ghc-flag:`-H` without any argument to let GHC - calculate a value based on the amount of live data. + 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. Compact your data: The :compact-ref:`GHC.Compact <GHC-Compact.html>` module diff --git a/docs/users_guide/using-concurrent.rst b/docs/users_guide/using-concurrent.rst index d62b811345..f0236a3ced 100644 --- a/docs/users_guide/using-concurrent.rst +++ b/docs/users_guide/using-concurrent.rst @@ -16,7 +16,7 @@ for that module. Optionally, the program may be linked with the :ghc-flag:`-threaded` option (see :ref:`options-linker`. This provides two benefits: -- It enables the :rts-flag:`-N` to be used, which allows threads to run in +- It enables the :rts-flag:`-N ⟨x⟩` to be used, which allows threads to run in parallelism on a multi-processor or multi-core machine. See :ref:`using-smp`. - If a thread makes a foreign call (and the call is not marked @@ -31,7 +31,7 @@ programs: .. index:: single: RTS options; concurrent -.. rts-flag:: -C <s> +.. rts-flag:: -C ⟨s⟩ :default: 20 milliseconds @@ -107,8 +107,8 @@ There are two ways to run a program on multiple processors: call ``Control.Concurrent.setNumCapabilities`` from your program, or use the RTS ``-N`` options. -.. rts-flag:: -N <x> - -maxN <x> +.. rts-flag:: -N ⟨x⟩ + -maxN ⟨x⟩ Use ⟨x⟩ simultaneous threads when running the program. @@ -179,11 +179,11 @@ CPUs: Hints for using SMP parallelism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Add the :rts-flag:`-s` RTS option when running the program to see timing stats, -which will help to tell you whether your program got faster by using -more CPUs or not. If the user time is greater than the elapsed time, -then the program used more than one CPU. You should also run the program -without :rts-flag:`-N` for comparison. +Add the :rts-flag:`-s [⟨file⟩]` RTS option when running the program to see +timing stats, which will help to tell you whether your program got faster by +using more CPUs or not. If the user time is greater than the elapsed time, then +the program used more than one CPU. You should also run the program without +:rts-flag:`-N ⟨x⟩` for comparison. The output of ``+RTS -s`` tells you how many "sparks" were created and executed during the run of the program (see :ref:`rts-options-gc`), diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index 185e590534..15916b2690 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -171,9 +171,11 @@ by saying ``-fno-wombat``. to their usage sites. It also inlines simple expressions like literals or registers. -.. ghc-flag:: -fcpr-off +.. ghc-flag:: -fcpr-anal - Switch off CPR analysis in the demand analyser. + :default: on + + Turn on CPR analysis in the demand analyser. .. ghc-flag:: -fcse @@ -343,7 +345,7 @@ by saying ``-fno-wombat``. a bit like the call-pattern specialiser (:ghc-flag:`-fspec-constr`) but for free variables rather than arguments. -.. ghc-flag:: -fliberate-case-threshold=<n> +.. ghc-flag:: -fliberate-case-threshold=⟨n⟩ :default: 2000 @@ -357,7 +359,7 @@ by saying ``-fno-wombat``. self-recursive saturated tail calls into local jumps rather than function calls. -.. ghc-flag:: -fmax-inline-alloc-size=<n> +.. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩ :default: 128 @@ -366,20 +368,20 @@ by saying ``-fno-wombat``. nursery block if they're no bigger than n bytes, ignoring GC overheap. This value should be quite a bit smaller than the block size (typically: 4096). -.. ghc-flag:: -fmax-inline-memcpy-insn=<n> +.. ghc-flag:: -fmax-inline-memcpy-insns=⟨n⟩ :default: 32 Inline ``memcpy`` calls if they would generate no more than ⟨n⟩ pseudo-instructions. -.. ghc-flag:: -fmax-inline-memset-insns=<n> +.. ghc-flag:: -fmax-inline-memset-insns=⟨n⟩ :default: 32 Inline ``memset`` calls if they would generate no more than n pseudo instructions. -.. ghc-flag:: -fmax-relevant-binds=<n> +.. ghc-flag:: -fmax-relevant-binds=⟨n⟩ -fno-max-relevant-bindings :default: 6 @@ -392,7 +394,7 @@ by saying ``-fno-wombat``. they may be numerous), but ``-fno-max-relevant-bindings`` includes them too. -.. ghc-flag:: -fmax-valid-substitutions=<n> +.. ghc-flag:: -fmax-valid-substitutions=⟨n⟩ -fno-max-valid-substitutions :default: 6 @@ -402,20 +404,20 @@ by saying ``-fno-wombat``. set by this flag. Turning it off with ``-fno-max-valid-substitutions`` gives an unlimited number. -.. ghc-flag:: -fmax-uncovered-patterns=<n> +.. ghc-flag:: -fmax-uncovered-patterns=⟨n⟩ :default: 4 Maximum number of unmatched patterns to be shown in warnings generated by :ghc-flag:`-Wincomplete-patterns` and :ghc-flag:`-Wincomplete-uni-patterns`. -.. ghc-flag:: -fmax-simplifier-iterations=<n> +.. ghc-flag:: -fmax-simplifier-iterations=⟨n⟩ :default: 4 Sets the maximal number of iterations for the simplifier. -.. ghc-flag:: -fmax-worker-args=<n> +.. ghc-flag:: -fmax-worker-args=⟨n⟩ :default: 10 @@ -497,13 +499,13 @@ by saying ``-fno-wombat``. as the :ghc-flag:`-fregs-graph` one but also enables iterative coalescing during register allocation. -.. ghc-flag:: -fsimplifier-phases=<n> +.. ghc-flag:: -fsimplifier-phases=⟨n⟩ :default: 2 Set the number of phases for the simplifier. Ignored with ``-O0``. -.. ghc-flag:: -fsimpl-tick-factor=<n> +.. ghc-flag:: -fsimpl-tick-factor=⟨n⟩ :default: 100 @@ -597,14 +599,14 @@ by saying ``-fno-wombat``. beneficial; e.g. the argument might be given to some other function that can itself be specialised. -.. ghc-flag:: -fspec-constr-count=<n> +.. ghc-flag:: -fspec-constr-count=⟨n⟩ :default: 3 Set the maximum number of specialisations that will be created for any one function by the SpecConstr transformation. -.. ghc-flag:: -fspec-constr-threshold=<n> +.. ghc-flag:: -fspec-constr-threshold=⟨n⟩ :default: 2000 @@ -757,7 +759,7 @@ by saying ``-fno-wombat``. Alternatively you can use :ghc-flag:`-funbox-small-strict-fields` to only unbox strict fields which are "small". -.. ghc-flag:: -funfolding-creation-threshold=<n> +.. ghc-flag:: -funfolding-creation-threshold=⟨n⟩ :default: 750 @@ -776,11 +778,11 @@ by saying ``-fno-wombat``. a. nothing larger than this will be inlined (unless it has an ``INLINE`` pragma) b. nothing larger than this will be spewed into an interface file. - Increasing this figure is more likely to result in longer compile - times than faster code. The :ghc-flag:`-funfolding-use-threshold` is more + Increasing this figure is more likely to result in longer compile times + than faster code. The :ghc-flag:`-funfolding-use-threshold=⟨n⟩` is more useful. -.. ghc-flag:: -funfolding-dict-discount=<n> +.. ghc-flag:: -funfolding-dict-discount=⟨n⟩ :default: 30 @@ -790,7 +792,7 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline dictionaries? -.. ghc-flag:: -funfolding-fun-discount=<n> +.. ghc-flag:: -funfolding-fun-discount=⟨n⟩ :default: 60 @@ -800,7 +802,7 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline functions? -.. ghc-flag:: -funfolding-keeness-factor=<n> +.. ghc-flag:: -funfolding-keeness-factor=⟨n⟩ :default: 1.5 @@ -810,7 +812,7 @@ by saying ``-fno-wombat``. How eager should the compiler be to inline functions? -.. ghc-flag:: -funfolding-use-threshold=<n> +.. ghc-flag:: -funfolding-use-threshold=⟨n⟩ :default: 60 @@ -825,10 +827,11 @@ by saying ``-fno-wombat``. minus any discounts that apply depending on the context into which the expression is to be inlined. - The difference between this and :ghc-flag:`-funfolding-creation-threshold` - is that this one determines if a function definition will be inlined - *at a call site*. The other option determines if a function - definition will be kept around at all for potential inlining. + The difference between this and + :ghc-flag:`-funfolding-creation-threshold=⟨n⟩` is that this one determines + if a function definition will be inlined *at a call site*. The other option + determines if a function definition will be kept around at all for + potential inlining. .. ghc-flag:: -fvectorisation-avoidance diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst index 9f10efb866..ce2de5c3ac 100644 --- a/docs/users_guide/using-warnings.rst +++ b/docs/users_guide/using-warnings.rst @@ -104,7 +104,7 @@ to abort. Makes any warning into a fatal error. Useful so that you don't miss warnings when doing batch compilation. -.. ghc-flag:: -Werror=<wflag> +.. ghc-flag:: -Werror=⟨wflag⟩ :noindex: :implies: ``-W<wflag>`` @@ -117,7 +117,7 @@ to abort. Warnings are treated only as warnings, not as errors. This is the default, but can be useful to negate a :ghc-flag:`-Werror` flag. -.. ghc-flag:: -Wwarn=<wflag> +.. ghc-flag:: -Wwarn=⟨wflag⟩ :noindex: Causes a specific warning to be treated as normal warning, not fatal error. @@ -562,7 +562,7 @@ of ``-W(no-)*``. h = \[] -> 2 Just k = f y -.. ghc-flag:: -fmax-pmcheck-iterations=<N> +.. ghc-flag:: -fmax-pmcheck-iterations=⟨n⟩ :default: 2000000 diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst index 84dae9fd0b..822199a436 100644 --- a/docs/users_guide/using.rst +++ b/docs/users_guide/using.rst @@ -309,7 +309,7 @@ The available mode flags are: generate dependency information suitable for use in a ``Makefile``. See :ref:`makefile-dependencies`. -.. ghc-flag:: --frontend <module> +.. ghc-flag:: --frontend ⟨module⟩ .. index:: single: frontend plugins; using @@ -417,9 +417,9 @@ The main advantages to using ``ghc --make`` over traditional - GHC re-calculates the dependencies each time it is invoked, so the dependencies never get out of sync with the source. -- Using the :ghc-flag:`-j` flag, you can compile modules in parallel. Specify - ``-j⟨N⟩`` to compile ⟨N⟩ jobs in parallel. If N is omitted, - then it defaults to the number of processors. +- Using the :ghc-flag:`-j[⟨n⟩]` flag, you can compile modules in parallel. + Specify ``-j ⟨n⟩`` to compile ⟨n⟩ jobs in parallel. If ⟨n⟩ is omitted, then + it defaults to the number of processors. Any of the command-line options described in the rest of this chapter can be used with ``--make``, but note that any options you give on the @@ -445,7 +445,7 @@ The source files for the program don't all need to be in the same directory; the :ghc-flag:`-i` option can be used to add directories to the search path (see :ref:`search-path`). -.. ghc-flag:: -j [N] +.. ghc-flag:: -j[⟨n⟩] Perform compilation in parallel when possible. GHC will use up to ⟨N⟩ threads during compilation. If N is omitted, then it defaults to the @@ -549,10 +549,11 @@ to compile the Haskell source file ``Foo.hs`` to an object file Overriding the default behaviour for a file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As described above, the way in which a file is processed by GHC depends -on its suffix. This behaviour can be overridden using the :ghc-flag:`-x` option: +As described above, the way in which a file is processed by GHC depends on its +suffix. This behaviour can be overridden using the :ghc-flag:`-x ⟨suffix⟩` +option: -.. ghc-flag:: -x <suffix> +.. ghc-flag:: -x ⟨suffix⟩ Causes all files following this option on the command line to be processed as if they had the suffix ⟨suffix⟩. For example, to @@ -791,7 +792,7 @@ messages and in GHCi: in a’ or by using the flag -fno-warn-unused-do-bind -.. ghc-flag:: -fdiagnostics-color=(always|auto|never) +.. ghc-flag:: -fdiagnostics-color=⟨always|auto|never⟩ 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 @@ -867,7 +868,7 @@ messages and in GHCi: start at zero. This choice was made to follow existing convention (i.e. this is how Emacs does it). -.. ghc-flag:: -H <size> +.. ghc-flag:: -H ⟨size⟩ Set the minimum size of the heap to ⟨size⟩. This option is equivalent to ``+RTS -Hsize``, see :ref:`rts-options-gc`. |