Commit 44b090be authored by patrickdoc's avatar patrickdoc Committed by Ben Gamari
Browse files

users-guide: Standardize and repair all flag references

This patch does three things:

1.) It simplifies the flag parsing code in `conf.py` to properly display
flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
references must include the associated arguments. Documentation has been
added to `editing-guide.rst` to explain this.

2.) It normalizes all flag definitions to a similar format. Notably, all
instances of `<>` have been replaced with `⟨⟩`. All references across the
users guide have been updated to match.

3.) It fixes a couple issues with the flag reference table's generation code,
which did not handle comma separated flags in the same cell and did not
properly reference flags with arguments.

Test Plan:
`SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
references. All remaining errors are references to flags without any
documentation.

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #13980

Differential Revision: https://phabricator.haskell.org/D3778
parent d4e97212
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
......@@ -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.
......
......@@ -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
......
......@@ -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`).
......
......@@ -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).