Documentation for -fexternal-interpreter

4 files changed, 77 insertions, 2 deletions

diff --git a/docs/users_guide/7.12.1-notes.rst b/docs/users_guide/7.12.1-notes.rst
index 77d012ba60..749f7afbc1 100644
--- a/docs/users_guide/7.12.1-notes.rst
+++ b/docs/users_guide/7.12.1-notes.rst
@@ -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
+  code.
+
 - The reworked users guide you are now reading
 
 
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index 06cc7a2dc3..272f05a83f 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -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.
+
+``-fexternal-interpreter``
+    .. 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
+    ``-fexternal-interpreter``.
+
+    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
diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 30a1b68f2b..da08c7b514 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -10097,6 +10097,8 @@ Run "main.exe" and here is your output:
     $ ./main
     Hello
 
+.. _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:
+splices.
+
+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
+releases).
 
 .. _th-quasiquotation:
 
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 27b54cb0a8..1c48cfceb6 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -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
 required).