[commit: ghc] wip/angerman/iserv-proxy-cleanup: Adds some documentation. (23cc744)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/angerman/iserv-proxy-cleanup
Link       : http://ghc.haskell.org/trac/ghc/changeset/23cc7440ad1c78c5c3c2510a43807bd138dd3322/ghc

>---------------------------------------------------------------

commit 23cc7440ad1c78c5c3c2510a43807bd138dd3322
Author: Moritz Angermann <moritz.angermann at gmail.com>
Date:   Wed Jan 30 10:17:40 2019 +0800

    Adds some documentation.


>---------------------------------------------------------------

23cc7440ad1c78c5c3c2510a43807bd138dd3322
 docs/users_guide/ghci.rst | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index f468e80..7eab38d 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -3287,6 +3287,38 @@ dynamically-linked) from GHC itself.  So for example:
 This feature is experimental in GHC 8.0.x, but it may become the
 default in future releases.
 
+.. _external-interpreter-proxy:
+
+Running the interpreter on a different host
+-------------------------------------------
+
+When using the flag :ghc-flag:`-fexternal-interpreter` GHC will
+spawn and communicate with the separate process using pipes.  There
+are scenarios (e.g. when cross compiling) where it is favourable to
+have the communication happen over the network. GHC provides two
+utilities for this, which can be found in the ``utils`` directory.
+
+- ``remote-iserv`` needs to be built with the cross compiler to be
+  executed on the remote host. Or in the case of using it on the
+  same host the stage2 compiler will do as well.
+
+- ``iserv-proxy`` needs to be built on the build machine by the
+  build compiler.
+
+After starting ``remote-iserv ⟨tmp_dir⟩ ⟨port⟩`` on the target and
+providing it with a temporary folder (where it will copy the
+necessary libraries to load to) and port it will listen for
+the proxy to connect.
+
+Providing :ghc-flag:`-pgmi /path/to/iserv-proxy`, :ghc-flag:`-pgmo ⟨option⟩`
+and :ghc-flag:`-pgmo ⟨port⟩` in addition to :ghc-flag:`-fexternal-interpreter`
+will then make ghc go through the proxy instead.
+
+There are some limitations when using this. File and process IO
+will be executed on the target. As such packages like git-embed,
+file-embed and others might not behave as expected if the target
+and host do not share the same filesystem.
+
 .. _ghci-faq:
 
 FAQ and Things To Watch Out For