From 23cc7440ad1c78c5c3c2510a43807bd138dd3322 Mon Sep 17 00:00:00 2001 From: Moritz Angermann Date: Wed, 30 Jan 2019 10:17:40 +0800 Subject: Adds some documentation. --- 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 f468e80eb0..7eab38daff 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 -- cgit v1.2.1