[readme] Add JShell description

Author: JakubVanek

README.md

@@ -13,6 +13,25 @@ The output consists of these parts:
   * It has `javac` (jdk.compiler module).
   * JShell remote launcher (hackish, linux-only) is available.
 
+## JShell hack
+We've managed to run JShell in a kind of "split-mode". The compiler part runs on your powerful computer,
+whether the not-so-demanding execution is done on the brick. This was almost supported out of the box - 
+the default JShell configuration already uses JDI transport. The only issue is that it does not provide an
+intuitive way to connect to a remote host. JShell always launches a new JVM process in the JDI mode.
+
+Our hack relies on replacing the agent in the VM started by JShell. The new dummy agent just
+writes the port number it was supposed to connect to a file `/tmp/jshellargs`. Then, if you make
+`jshellargs` a UNIX pipe, you can very easily pass the port to another application.
+
+JShell on your computer is the listening side of the JDWP channel. To reuse the existing remote agent,
+which is used in the local JDI mode, we tunnel a chosen port over the SSH session. SSH connects to the 
+JShell listening socket and itself listens on the remote side. Then, the last task is to run the
+JShell JDI agent on the remote side, which is handled by SSH as well.
+
+Practically, first you have to either [add](https://askubuntu.com/a/4833) your pubkey to the EV3 brick's authorized_keys,
+or set the [SSH_ASKPASS](https://unix.stackexchange.com/a/83991) environment variable. Then, run a script from
+the amd64 JDK: `bin/jshell-launch.sh <ssh args>`, where `<ssh args>` is an address with an optinal port-specifying flag.
+The options are just added to the SSH command line and aren't sanitized in any way.
 
 ## Building