users-guide: Fix -rtsopts default
[ghc.git] / docs / users_guide / phases.rst
index 0428956..fb66370 100644 (file)
@@ -18,46 +18,79 @@ following options allow you to change the external program used for a
 given compilation phase:
 
 .. ghc-flag:: -pgmL ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the literate pre-processor
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the literate pre-processor.
 
 .. ghc-flag:: -pgmP ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only)
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the C pre-processor (with ``-cpp`` only).
 
 .. ghc-flag:: -pgmc ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the C compiler
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the C compiler.
 
 .. ghc-flag:: -pgmlo ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the LLVM optimiser
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the LLVM optimiser.
 
 .. ghc-flag:: -pgmlc ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the LLVM compiler
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the LLVM compiler.
 
 .. ghc-flag:: -pgms ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the splitter
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the splitter.
 
 .. ghc-flag:: -pgma ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the assembler
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the assembler.
 
 .. ghc-flag:: -pgml ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the linker
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the linker.
 
 .. ghc-flag:: -pgmdll ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the DLL generator
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the DLL generator.
 
 .. ghc-flag:: -pgmF ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the pre-processor (with ``-F`` only)
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the pre-processor (with ``-F`` only).
 
 .. ghc-flag:: -pgmwindres ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the program for embedding manifests on Windows.
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the program to use for embedding manifests on Windows.
     Normally this is the program ``windres``, which is supplied with a
@@ -65,10 +98,16 @@ given compilation phase:
     :ref:`options-linker`.
 
 .. ghc-flag:: -pgmlibtool ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the command for libtool (with ``-staticlib`` only).
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the libtool command (when using ``-staticlib`` only).
 
 .. ghc-flag:: -pgmi ⟨cmd⟩
+    :shortdesc: Use ⟨cmd⟩ as the external interpreter command.
+    :type: dynamic
+    :category: phase-programs
 
     Use ⟨cmd⟩ as the external interpreter command (see:
     :ref:`external-interpreter`).  Default: ``ghc-iserv-prof`` if
@@ -87,48 +126,88 @@ Options can be forced through to a particular compilation phase, using
 the following flags:
 
 .. ghc-flag:: -optL ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the literate pre-processor
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the literate pre-processor
 
 .. ghc-flag:: -optP ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to cpp (with ``-cpp`` only)
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to CPP (makes sense only if ``-cpp`` is also on).
 
 .. ghc-flag:: -optF ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the custom pre-processor
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the custom pre-processor (see
     :ref:`pre-processor`).
 
 .. ghc-flag:: -optc ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the C compiler
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the C compiler.
 
+.. ghc-flag:: -optcxx ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the C++ compiler
+    :type: dynamic
+    :category: phase-options
+
+    Pass ⟨option⟩ to the C++ compiler.
+
 .. ghc-flag:: -optlo ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the LLVM optimiser
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the LLVM optimiser.
 
 .. ghc-flag:: -optlc ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the LLVM compiler
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the LLVM compiler.
 
 .. ghc-flag:: -opta ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the assembler
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the assembler.
 
 .. ghc-flag:: -optl ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the linker
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the linker.
 
 .. ghc-flag:: -optdll ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the DLL generator
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the DLL generator.
 
 .. ghc-flag:: -optwindres ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to ``windres``.
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to ``windres`` when embedding manifests on Windows.
     See ``-fno-embed-manifest`` in :ref:`options-linker`.
 
 .. ghc-flag:: -opti ⟨option⟩
+    :shortdesc: pass ⟨option⟩ to the interpreter sub-process.
+    :type: dynamic
+    :category: phase-options
 
     Pass ⟨option⟩ to the interpreter sub-process (see
     :ref:`external-interpreter`).  A common use for this is to pass
@@ -149,29 +228,53 @@ to GHC's runtime system you can enclose them in ``+RTS ... -RTS`` (see
 Options affecting the C pre-processor
 -------------------------------------
 
+.. extension:: CPP
+    :shortdesc: Enable the C preprocessor.
+
+    :since: 6.8.1
+
 .. index::
    single: pre-processing: cpp
    single: C pre-processor options
    single: cpp, pre-processing with
 
 .. ghc-flag:: -cpp
+    :shortdesc: Run the C pre-processor on Haskell source files
+    :type: dynamic
+    :category: cpp
 
     The C pre-processor :command:`cpp` is run over your Haskell code only if
     the ``-cpp`` option -cpp option is given. Unless you are building a
     large system with significant doses of conditional compilation, you
     really shouldn't need it.
 
-.. ghc-flag:: -D ⟨symbol⟩[=⟨value⟩]
+.. ghc-flag:: -D⟨symbol⟩[=⟨value⟩]
+    :shortdesc: Define a symbol in the C pre-processor
+    :type: dynamic
+    :reverse: -U⟨symbol⟩
+    :category: cpp
 
-    Define macro ⟨symbol⟩ in the usual way. NB: does *not* affect ``-D``
-    macros passed to the C compiler when compiling via C! For those, use
-    the ``-optc-Dfoo`` hack… (see :ref:`forcing-options-through`).
+    Define macro ⟨symbol⟩ in the usual way. 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⟩
+    .. note::
+
+        :ghc-flag:`-D⟨symbol⟩[=⟨value⟩]` does *not* affect ``-D``
+        macros passed to the C compiler when compiling an unregisterised build! In
+        this case use the ``-optc-Dfoo`` hack… (see :ref:`forcing-options-through`).
+
+.. ghc-flag:: -U⟨symbol⟩
+    :shortdesc: Undefine a symbol in the C pre-processor
+    :type: dynamic
+    :category: cpp
 
     Undefine macro ⟨symbol⟩ in the usual way.
 
-.. ghc-flag:: -I ⟨dir⟩
+.. ghc-flag:: -I⟨dir⟩
+    :shortdesc: Add ⟨dir⟩ to the directory search list for ``#include`` files
+    :type: dynamic
+    :category: cpp
 
     Specify a directory in which to look for ``#include`` files, in the
     usual C way.
@@ -179,6 +282,11 @@ Options affecting the C pre-processor
 The GHC driver pre-defines several macros when processing Haskell source
 code (``.hs`` or ``.lhs`` files).
 
+.. _standard-cpp-macros:
+
+Standard CPP macros
+~~~~~~~~~~~~~~~~~~~
+
 The symbols defined by GHC are listed below. To check which symbols are
 defined by your local GHC installation, the following trick is useful:
 
@@ -255,7 +363,7 @@ defined by your local GHC installation, the following trick is useful:
     is required, the presence of the ``MIN_VERSION_GLASGOW_HASKELL``
     macro needs to be ensured before it is called, e.g.:
 
-    .. code-block: c
+    .. code-block:: c
 
         #ifdef MIN_VERSION_GLASGOW_HASKELL
         #if MIN_VERSION_GLASGOW_HASKELL(7,10,2,0)
@@ -283,7 +391,9 @@ defined by your local GHC installation, the following trick is useful:
 
     Only defined when ``-fllvm`` is specified. When GHC is using version
     ``x.y.z`` of LLVM, the value of ``__GLASGOW_HASKELL_LLVM__`` is the
-    integer ⟨xy⟩.
+    integer ⟨xyy⟩ (if ⟨y⟩ is a single digit, then a leading zero
+    is added, so for example when using version 3.7 of LLVM,
+    ``__GLASGOW_HASKELL_LLVM__==307``).
 
 ``__PARALLEL_HASKELL__``
     .. index::
@@ -305,18 +415,16 @@ defined by your local GHC installation, the following trick is useful:
 
 ``VERSION_pkgname``
     This macro is available starting GHC 8.0.  It is defined for every
-    exposed package, but only if the ``-hide-all-packages`` flag
-    is set.  This macro expands to a string recording the
+    exposed package. This macro expands to a string recording the
     version of ``pkgname`` that is exposed for module import.
     It is identical in behavior to the ``VERSION_pkgname`` macros
     that Cabal defines.
 
 ``MIN_VERSION_pkgname(x,y,z)``
     This macro is available starting GHC 8.0.  It is defined for every
-    exposed package, but only if the ``-hide-all-packages`` flag
-    is set. This macro is provided for convenience to write CPP
+    exposed package. This macro is provided for convenience to write CPP
     conditionals testing if a package version is ``x.y.z`` or
-    less.  It is identical in behavior to the ``MIN_VERSION_pkgname``
+    later.  It is identical in behavior to the ``MIN_VERSION_pkgname``
     macros that Cabal defines.
 
 .. _cpp-string-gaps:
@@ -352,6 +460,10 @@ Options affecting a Haskell pre-processor
    single: pre-processor options
 
 .. ghc-flag:: -F
+    :shortdesc: Enable the use of a :ref:`pre-processor <pre-processor>`
+        (set with :ghc-flag:`-pgmF ⟨cmd⟩`)
+    :type: dynamic
+    :category: phases
 
     A custom pre-processor is run over your Haskell source file only if
     the ``-F`` option is given.
@@ -368,16 +480,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``
@@ -401,11 +513,19 @@ Options affecting code generation
 ---------------------------------
 
 .. ghc-flag:: -fasm
+    :shortdesc: Use the :ref:`native code generator <native-code-gen>`
+    :type: dynamic
+    :reverse: -fllvm
+    :category: codegen
 
     Use GHC's :ref:`native code generator <native-code-gen>` rather than
     compiling via LLVM. ``-fasm`` is the default.
 
 .. ghc-flag:: -fllvm
+    :shortdesc: Compile using the :ref:`LLVM code generator <llvm-code-gen>`
+    :type: dynamic
+    :reverse: -fasm
+    :category: codegen
 
     Compile via :ref:`LLVM <llvm-code-gen>` instead of using the native
     code generator. This will generally take slightly longer than the
@@ -414,12 +534,23 @@ Options affecting code generation
     via LLVM requires LLVM's :command:`opt` and :command:`llc` executables to be
     in :envvar:`PATH`.
 
+    .. note::
+
+        Note that this GHC release expects an LLVM version in the |llvm-version|
+        release series.
+
 .. ghc-flag:: -fno-code
+    :shortdesc: Omit code generation
+    :type: dynamic
+    :category: codegen
 
     Omit code generation (and all later phases) altogether. This is
     useful if you're only interested in type checking code.
 
 .. ghc-flag:: -fwrite-interface
+    :shortdesc: Always write interface files
+    :type: dynamic
+    :category: codegen
 
     Always write interface files. GHC will normally write interface
     files automatically, but this flag is useful with :ghc-flag:`-fno-code`,
@@ -428,12 +559,18 @@ Options affecting code generation
     compiling dependencies.
 
 .. ghc-flag:: -fobject-code
+    :shortdesc: Generate object code
+    :type: dynamic
+    :category: codegen
 
     Generate object code. This is the default outside of GHCi, and can
     be used with GHCi to cause object code to be generated in preference
     to bytecode.
 
 .. ghc-flag:: -fbyte-code
+    :shortdesc: Generate byte-code
+    :type: dynamic
+    :category: codegen
 
     Generate byte-code instead of object-code. This is the default in
     GHCi. Byte-code can currently only be used in the interactive
@@ -441,20 +578,67 @@ Options affecting code generation
     reversing the effect of :ghc-flag:`-fobject-code`.
 
 .. ghc-flag:: -fPIC
+    :shortdesc: Generate position-independent code (where available)
+    :type: dynamic
+    :category: codegen
 
     Generate position-independent code (code that can be put into shared
     libraries). This currently works on Linux x86 and x86-64. On
     Windows, position-independent code is never used so the flag is a
     no-op on that platform.
 
+.. ghc-flag:: -fexternal-dynamic-refs
+    :shortdesc: Generate code for linking against dynamic libraries
+    :type: dynamic
+    :category: codegen
+
+    When generating code, assume that entities imported from a
+    different module might be dynamically linked.  This flag is enabled
+    automatically by :ghc-flag:`-dynamic`.
+
+.. ghc-flag:: -fPIE
+    :shortdesc: Generate code for a position-independent executable (where available)
+    :type: dynamic
+    :category: codegen
+
+    Generate code in such a way to be linkable into a position-independent
+    executable This currently works on Linux x86 and x86-64. On Windows,
+    position-independent code is never used so the flag is a no-op on that
+    platform. To link the final executable use :ghc-flag:`-pie`.
+
 .. ghc-flag:: -dynamic
+    :shortdesc: Build dynamically-linked object files and executables
+    :type: dynamic
+    :category: codegen
+    :noindex:
 
-    When generating code, assume that entities imported from a different
-    package will reside in a different shared library or binary.
+    Build code for dynamic linking.  This can reduce code size
+    tremendously, but may slow-down cross-module calls of non-inlined
+    functions. There can be some complications combining
+    :ghc-flag:`-shared` with this flag relating to linking in the RTS
+    under Linux. See :ghc-ticket:`10352`.
 
     Note that using this option when linking causes GHC to link against
     shared libraries.
 
+.. ghc-flag:: -dynamic-too
+    :shortdesc: Build dynamic object files *as well as* static object files
+        during compilation
+    :type: dynamic
+    :category: codegen
+
+    Generates both dynamic and static object files in a single run of
+    GHC. This option is functionally equivalent to running GHC twice,
+    the second time adding ``-dynamic -osuf dyn_o -hisuf dyn_hi``.
+
+    Although it is equivalent to running GHC twice, using
+    ``-dynamic-too`` is more efficient, because the earlier phases of
+    the compiler up to code generation are performed just once.
+
+    When using ``-dynamic-too``, the options ``-dyno``, ``-dynosuf``,
+    and ``-dynhisuf`` are the counterparts of ``-o``, ``-osuf``, and
+    ``-hisuf`` respectively, but applying to the dynamic compilation.
+
 .. _options-linker:
 
 Options affecting linking
@@ -469,6 +653,9 @@ user-supplied, GHC-supplied, and system-supplied (``-lm`` math library,
 for example).
 
 .. ghc-flag:: -l ⟨lib⟩
+    :shortdesc: Link in library ⟨lib⟩
+    :type: dynamic
+    :category: linking
 
     Link in the ⟨lib⟩ library. On Unix systems, this will be in a file
     called :file:`lib{lib}.a` or :file:`lib{lib}.so` which resides somewhere on the
@@ -481,21 +668,25 @@ for example).
 
     There's one other gotcha to bear in mind when using external
     libraries: if the library contains a ``main()`` function, then this
-    will be linked in preference to GHC's own ``main()`` function (eg.
-    ``libf2c`` and ``libl`` have their own ``main()``\ s). This is
-    because GHC's ``main()`` comes from the ``HSrts`` library, which is
-    normally included *after* all the other libraries on the linker's
-    command line. To force GHC's ``main()`` to be used in preference to
-    any other ``main()``\ s from external libraries, just add the option
-    ``-lHSrts`` before any other libraries on the command line.
+    will be a link conflict with GHC's own ``main()`` function (eg.
+    ``libf2c`` and ``libl`` have their own ``main()``\ s).
+
+    You can use an external main function if you initialize the RTS manually
+    and pass ``-no-hs-main``. See also :ref:`using-own-main`.
 
 .. ghc-flag:: -c
+    :shortdesc: Stop after generating object (``.o``) file
+    :type: mode
+    :category: linking
 
     Omits the link step. This option can be used with :ghc-flag:`--make` to
     avoid the automatic linking that takes place if the program contains
     a ``Main`` module.
 
 .. ghc-flag:: -package ⟨name⟩
+    :shortdesc: Expose package ⟨pkg⟩
+    :type: dynamic
+    :category: linking
 
     If you are using a Haskell "package" (see :ref:`packages`), don't
     forget to add the relevant ``-package`` option when linking the
@@ -504,6 +695,10 @@ for example).
     result in several pages of link errors.
 
 .. ghc-flag:: -framework ⟨name⟩
+    :shortdesc: On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This
+        option corresponds to the ``-framework`` option for Apple's Linker.
+    :type: dynamic
+    :category: linking
 
     On Darwin/OS X/iOS only, link in the framework ⟨name⟩. This option
     corresponds to the ``-framework`` option for Apple's Linker. Please
@@ -513,38 +708,41 @@ for example).
     for example, you'd use ``-framework Carbon``.
 
 .. ghc-flag:: -staticlib
+    :shortdesc: Generate a standalone static library (as opposed to an
+        executable). This is useful when cross compiling. The
+        library together with all its dependencies ends up in in a
+        single static library that can be linked against.
+    :type: dynamic
+    :category: linking
 
-    On Darwin/OS X/iOS only, link all passed files into a static library
-    suitable for linking into an iOS (when using a cross-compiler) or
-    Mac Xcode project. To control the name, use the :ghc-flag:`-o` ⟨name⟩ option
-    as usual. The default name is ``liba.a``. This should nearly always
-    be passed when compiling for iOS with a cross-compiler.
+    Link all passed files into a static library suitable for linking.
+    To control the name, use the :ghc-flag:`-o ⟨file⟩` option
+    as usual. The default name is ``liba.a``.
 
 .. ghc-flag:: -L ⟨dir⟩
+    :shortdesc: Add ⟨dir⟩ to the list of directories searched for libraries
+    :type: dynamic
+    :category: linking
 
     Where to find user-supplied libraries… Prepend the directory ⟨dir⟩
     to the library directories path.
 
 .. ghc-flag:: -framework-path ⟨dir⟩
+    :shortdesc: On Darwin/OS X/iOS only, add ⟨dir⟩ to the list of directories
+        searched for frameworks. This option corresponds to the ``-F``
+        option for Apple's Linker.
+    :type: dynamic
+    :category: linking
 
     On Darwin/OS X/iOS only, prepend the directory ⟨dir⟩ to the
     framework directories path. This option corresponds to the ``-F``
     option for Apple's Linker (``-F`` already means something else for
     GHC).
 
-.. ghc-flag:: -split-objs
-
-    Tell the linker to split the single object file that would normally
-    be generated into multiple object files, one per top-level Haskell
-    function or type in the module. This only makes sense for libraries,
-    where it means that executables linked against the library are
-    smaller as they only link against the object files that they need.
-    However, assembling all the sections separately is expensive, so
-    this is slower than compiling normally. Additionally, the size of
-    the library itself (the ``.a`` file) can be a factor of 2 to 2.5
-    larger. We use this feature for building GHC's libraries.
-
 .. ghc-flag:: -split-sections
+    :shortdesc: Split sections for link-time dead-code stripping
+    :type: dynamic
+    :category: linking
 
     Place each generated function or data item into its own section in the
     output file if the target supports arbitrary sections. The name of the
@@ -552,16 +750,20 @@ for example).
     output file.
 
     When linking, the linker can automatically remove all unreferenced sections
-    and thus produce smaller executables. The effect is similar to
-    :ghc-flag:`-split-objs`, but somewhat more efficient - the generated library
-    files are about 30% smaller than with :ghc-flag:`-split-objs`.
+    and thus produce smaller executables.
 
 .. ghc-flag:: -static
+    :shortdesc: Use static Haskell libraries
+    :type: dynamic
+    :category: linking
 
     Tell the linker to avoid shared Haskell libraries, if possible. This
     is the default.
 
 .. ghc-flag:: -dynamic
+    :shortdesc: Build dynamically-linked object files and executables
+    :type: dynamic
+    :category: linking
 
     This flag tells GHC to link against shared Haskell libraries. This
     flag only affects the selection of dependent libraries, not the form
@@ -572,17 +774,20 @@ for example).
     above).
 
 .. ghc-flag:: -shared
+    :shortdesc: Generate a shared library (as opposed to an executable)
+    :type: dynamic
+    :category: linking
 
     Instead of creating an executable, GHC produces a shared object with
     this linker flag. Depending on the operating system target, this
     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`
@@ -592,12 +797,18 @@ for example).
     when linked against this package. See shared object name mangling.
 
 .. ghc-flag:: -dynload
+    :shortdesc: Selects one of a number of modes for finding shared libraries at runtime.
+    :type: dynamic
+    :category: linking
 
     This flag selects one of a number of modes for finding shared
     libraries at runtime. See :ref:`finding-shared-libs` for a
     description of each mode.
 
 .. ghc-flag:: -main-is ⟨thing⟩
+    :shortdesc: Set main module and function
+    :type: dynamic
+    :category: linking
 
     .. index::
        single: specifying your own main function
@@ -629,6 +840,9 @@ for example).
     :ghc-flag:`-fforce-recomp` flag.
 
 .. ghc-flag:: -no-hs-main
+    :shortdesc: Don't assume this program contains ``main``
+    :type: dynamic
+    :category: linking
 
     .. index::
        single: linking Haskell libraries with foreign code
@@ -650,13 +864,18 @@ 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|ignore|ignoreAll⟩]` 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|ignore|ignoreAll⟩]` and
+    :ghc-flag:`-with-rtsopts=⟨opts⟩` when using your own ``main``.
 
 .. ghc-flag:: -debug
+    :shortdesc: Use the debugging runtime
+    :type: dynamic
+    :category: linking
 
     Link the program with a debugging version of the runtime system. The
     debugging runtime turns on numerous assertions and sanity checks,
@@ -664,6 +883,9 @@ for example).
     (run the program with ``+RTS -?`` to see a list).
 
 .. ghc-flag:: -threaded
+    :shortdesc: Use the threaded runtime
+    :type: dynamic
+    :category: linking
 
     Link the program with the "threaded" version of the runtime system.
     The threaded runtime system is so-called because it manages multiple
@@ -676,10 +898,9 @@ for example).
 
     The threaded runtime system provides the following benefits:
 
-    -  It enables the :rts-flag:`-N` RTS option to be used,
-       which allows threads to run in parallelparallelism on a
-       multiprocessormultiprocessorSMP or multicoremulticore machine.
-       See :ref:`using-smp`.
+    -  It enables the :rts-flag:`-N ⟨x⟩` RTS option to be used,
+       which allows threads to run in parallel on a multiprocessor
+       or multicore machine. See :ref:`using-smp`.
 
     -  If a thread makes a foreign call (and the call is not marked
        ``unsafe``), then other Haskell threads in the program will
@@ -689,6 +910,9 @@ for example).
        :ref:`ffi-threads`.
 
 .. ghc-flag:: -eventlog
+    :shortdesc: Enable runtime event tracing
+    :type: dynamic
+    :category: linking
 
     Link the program with the "eventlog" version of the runtime system.
     A program linked in this way can generate a runtime trace of events
@@ -699,7 +923,21 @@ 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|ignore|ignoreAll⟩]
+    :shortdesc: Control whether the RTS behaviour can be tweaked via command-line
+        flags and the ``GHCRTS`` environment variable. Using ``none``
+        means no RTS flags can be given; ``some`` means only a minimum
+        of safe options can be given (the default); ``all`` (or no
+        argument at all) means that all RTS flags are permitted; ``ignore``
+        means RTS flags can be given, but are treated as regular arguments and
+        passed to the Haskell program as arguments; ``ignoreAll`` is the same as
+        ``ignore``, but ``GHCRTS`` is also ignored. ``-rtsopts`` does not
+        affect ``-with-rtsopts`` behavior; flags passed via ``-with-rtsopts``
+        are used regardless of ``-rtsopts``.
+    :type: dynamic
+    :category: linking
+
+    :default: some
 
     This option affects the processing of RTS control options given
     either on the command line or via the :envvar:`GHCRTS` environment
@@ -712,6 +950,15 @@ for example).
         then the program will emit a warning message, ``GHCRTS`` will be
         ignored, and the program will run as normal.
 
+    ``-rtsopts=ignore``
+        Disables all processing of RTS options. Unlike ``none`` this treats
+        all RTS flags appearing on the command line the same way as regular
+        arguments. (Passing them on to your program as arguments).
+        ``GHCRTS`` options will be processed normally.
+
+    ``-rtsopts=ignoreAll``
+        Same as ``ignore`` but also ignores ``GHCRTS``.
+
     ``-rtsopts=some``
         [this is the default setting] Enable only the "safe" RTS
         options: (Currently only ``-?`` and ``--info``.) Any other RTS
@@ -731,7 +978,13 @@ 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
+    ``-rtsopts`` does not affect RTS options passed via ``-with-rtsopts``;
+    those are used regardless of ``-rtsopts``.
+
+.. ghc-flag:: -with-rtsopts=⟨opts⟩
+    :shortdesc: Set the default RTS options to ⟨opts⟩.
+    :type: dynamic
+    :category: linking
 
     This option allows you to set the default RTS options at link-time.
     For example, ``-with-rtsopts="-H128m"`` sets the default heap size
@@ -741,19 +994,30 @@ for example).
     change RTS options at run-time, in which case ``-with-rtsopts``
     would be the *only* way to set them.)
 
+    Use the runtime flag :rts-flag:`--info` on the executable program
+    to see the options set with ``-with-rtsopts``.
+
     Note that ``-with-rtsopts`` has no effect when used with
     ``-no-hs-main``; see :ref:`using-own-main` for details.
 
 .. 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``.
+    :shortdesc: Don't print RTS suggestions about linking with
+        :ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]`.
+    :type: dynamic
+    :category: linking
+
+    This option disables RTS suggestions about linking with
+    :ghc-flag:`-rtsopts[=⟨none|some|all|ignore|ignoreAll⟩]` 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
+    :shortdesc: Do not generate a manifest file (Windows only)
+    :type: dynamic
+    :category: linking
 
     On Windows, GHC normally generates a manifestmanifest file when
     linking a binary. The manifest is placed in the file
@@ -785,22 +1049,27 @@ for example).
     below.
 
 .. ghc-flag:: -fno-embed-manifest
+    :shortdesc: Do not embed the manifest in the executable (Windows only)
+    :type: dynamic
+    :category: linking
 
     .. 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
+    :shortdesc: Don't generate an import library for a DLL (Windows only)
+    :type: dynamic
+    :category: linking
 
     DLLs on Windows are typically linked to by linking to a
     corresponding ``.lib`` or ``.dll.a`` — the so-called import library.
@@ -815,7 +1084,14 @@ 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⟩
+    :shortdesc: Set the install name (via ``-install_name`` passed to Apple's
+        linker), specifying the full install path of the library file.
+        Any libraries or executables that link with it later will pick
+        up that path as their runtime search location for it.
+        (Darwin/OS X only)
+    :type: dynamic
+    :category: linking
 
     On Darwin/OS X, dynamic libraries are stamped at build time with an
     "install name", which is the ultimate install path of the library
@@ -827,8 +1103,73 @@ for example).
     on other platforms.
 
 .. ghc-flag:: -rdynamic
+    :shortdesc: This instructs the linker to add all symbols, not only used
+        ones, to the dynamic symbol table. Currently Linux and
+        Windows/MinGW32 only. This is equivalent to using
+        ``-optl -rdynamic`` on Linux, and ``-optl -export-all-symbols``
+        on Windows.
+    :type: dynamic
+    :category: linking
 
     This instructs the linker to add all symbols, not only used ones, to
     the dynamic symbol table. Currently Linux and Windows/MinGW32 only.
     This is equivalent to using ``-optl -rdynamic`` on Linux, and
     ``-optl -export-all-symbols`` on Windows.
+
+.. ghc-flag:: -fwhole-archive-hs-libs
+    :shortdesc: When linking a binary executable, this inserts the flag
+        ``-Wl,--whole-archive`` before any ``-l`` flags for Haskell
+        libraries, and ``-Wl,--no-whole-archive`` afterwards
+    :type: dynamic
+    :category: linking
+
+    When linking a binary executable, this inserts the flag
+    ``-Wl,--whole-archive`` before any ``-l`` flags for Haskell
+    libraries, and ``-Wl,--no-whole-archive`` afterwards (on OS X, the
+    flag is ``-Wl,-all_load``, there is no equivalent for
+    ``-Wl,--no-whole-archive``).  This flag also disables the use of
+    ``-Wl,--gc-sections`` (``-Wl,-dead_strip`` on OS X).
+
+    This is for specialist applications that may require symbols
+    defined in these Haskell libraries at runtime even though they
+    aren't referenced by any other code linked into the executable.
+    If you're using ``-fwhole-archive-hs-libs``, you probably also
+    want ``-rdynamic``.
+
+.. ghc-flag:: -pie
+    :shortdesc: Instruct the linker to produce a position-independent executable.
+    :type: dynamic
+    :category: linking
+
+    :since: 8.2.2
+
+    This instructs the linker to produce a position-independent executable.
+    This flag is only valid while producing executables and all object code
+    being linked must have been produced with :ghc-flag:`-fPIE`.
+
+    Position independent executables are required by some platforms as they
+    enable address-space layout randomization (ASLR), a common security measure.
+    They can also be useful as they can be dynamically loaded and used as shared
+    libraries by other executables.
+
+    Position independent executables should be dynamically-linked (e.g. built
+    with :ghc-flag:`-dynamic` and only loaded into other dynamically-linked
+    executables to ensure that only one ``libHSrts`` is present if
+    loaded into the address space of another Haskell process.
+
+    Also, you may need to use the :ghc-flag:`-rdynamic` flag to ensure that
+    that symbols are not dropped from your PIE objects.
+
+.. ghc-flag:: -keep-cafs
+    :shortdesc: Do not garbage-collect CAFs (top-level expressions) at runtime
+    :type: dynamic
+    :category: linking
+
+    :since: 8.8.1
+
+    Disables the RTS's normal behaviour of garbage-collecting CAFs
+    (Constant Applicative Forms, in other words top-level
+    expressions). This option is useful for specialised applications
+    that do runtime dynamic linking, where code dynamically linked in
+    the future might require the value of a CAF that would otherwise
+    be garbage-collected.