Commit 34393d99 authored by Simon Marlow's avatar Simon Marlow

Documentation for -fexternal-interpreter

parent dc8b6474
......@@ -40,6 +40,10 @@ The highlights, since the 7.10 branch, are:
- A rewritten (and greatly improved) pattern exhaustiveness checker
- GHC can run the interpreter in a separate process (see
:ref:`external-interpreter`), and the interpreter can now run profiled
- The reworked users guide you are now reading
......@@ -2938,6 +2938,47 @@ breakpoints in object-code modules, for example. Only the exports of an
object-code module will be visible in GHCi, rather than all top-level
bindings as in interpreted modules.
.. _external-interpreter:
Running the interpreter in a separate process
Normally GHCi runs the interpreted code in the same process as GHC
itself, on top of the same RTS and sharing the same heap. However, if
the flag ``-fexternal-interpreter`` is given, then GHC will spawn a
separate process for running interpreted code, and communicate with it
using messages over a pipe.
.. index::
single: -fexternal-interpreter
Run interpreted code (for GHCi, Template Haskell, Quasi-quoting,
or Annotations) in a separate process. The interpreter will run
in profiling mode if ``-prof`` is in effect, and in
dynamically-linked mode if ``-dynamic`` is in effect.
There are a couple of caveats that will hopefully be removed in
the future: this option is currently not implemented on Windows
(it is a no-op), and the external interpreter does not support the
GHCi debugger, so breakpoints and single-stepping don't work with
See also the ``-pgmi`` (:ref:`replacing-phases`) and ``-opti``
(: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
dynamically-linked) from GHC itself. So for example, when compiling
Template Haskell code with ``-prof``, we don't need to compile the
modules without ``-prof`` first (see :ref:`th-profiling`) because we
can run the profiled object code in the interpreter. GHCi can also
load and run profiled object code when run with
``-fexternal-interpreter`` and ``-prof``.
This feature is experimental in GHC 8.0.x, but it may become the
default in future releases.
.. _ghci-faq:
FAQ and Things To Watch Out For
......@@ -10097,6 +10097,8 @@ Run "main.exe" and here is your output:
$ ./main
.. _th-profiling:
Using Template Haskell with Profiling
......@@ -10116,9 +10118,11 @@ runtime.
This causes difficulties if you have a multi-module program containing
Template Haskell code and you need to compile it for profiling, because
GHC cannot load the profiled object code and use it when executing the
splices. Fortunately GHC provides a workaround. The basic idea is to
compile the program twice:
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 ``-prof``.
......@@ -10136,6 +10140,13 @@ compile the program twice:
.. index::
single : ``-osuf``
The second option is to add the flag ``-fexternal-interpreter`` (see
:ref:`external-interpreter`), which runs the interpreter in a separate
process, wherein it can load and run the profiled code directly.
There's no need to compile the code twice, just add
``-fexternal-interpreter`` and it should just work. (this option is
experimental in GHC 8.0.x, but it may become the default in future
.. _th-quasiquotation:
......@@ -92,6 +92,15 @@ given compilation phase:
Use cmd as the libtool command (when using ``-staticlib`` only).
``-pgmi cmd``
.. index::
single: -pgmi
Use cmd as the external interpreter command (see:
:ref:`external-interpreter`). Default: ``ghc-iserv-prof`` if
``-prof`` is enabled, ``ghc-iserv-dyn`` if ``-dynamic`` is
enabled, or ``ghc-iserv`` otherwise.
.. _forcing-options-through:
Forcing options to a particular phase
......@@ -165,6 +174,16 @@ the following flags:
Pass option to ``windres`` when embedding manifests on Windows.
See ``-fno-embed-manifest`` in :ref:`options-linker`.
``-opti option``
.. index::
single: -opti
Pass option to the interpreter sub-process (see
:ref:`external-interpreter`). A common use for this is to pass
RTS options e.g., ``-opti+RTS -opti-A64m``, or to enable verbosity
with ``-opti-v`` to see what messages are being exchanged by GHC
and the interpreter.
So, for example, to force an ``-Ewurble`` option to the assembler, you
would tell the driver ``-opta-Ewurble`` (the dash before the E is
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment