(Re)generate: (find-channels-intro)
Source code: (find-eev "eev-intro.el" "find-channels-intro")
More intros: (find-eev-quick-intro)
(find-eev-intro)
(find-eval-intro)
(find-eepitch-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
1. Introduction
Before eepitch had been invented eev had two other ways to send
commands to external shell-like programs. The first way,
described here,
(find-prepared-intro)
(find-prepared-intro "2. `ee'")
was technically very simple: running `M-x eev' would save a
series of commands - usually the contents of the region - into a
temporary script file, and then the user would type something
like `ee' at the prompt of a ("prepared") shell; that would
make it read the saved commands and execute them.
Here we will describe the second of the Old Ways - one in which
the target program, which is usually a shell running in an xterm,
is sent a signal saying "execute the command NOW" as soon as a
command is saved into a temporary file by Emacs. The difficulty
is that this requires not only a directory for temporary files,
but also an Expect script, which acts as an intermediary that
listens to signals and handles them pretending that the saved
commands came from the keyboard... and, as some people have said,
this is "a nightmare to set up".
Here we explain the protocol - that can be adapted to other
cases too, like, for example, to make Emacs talk to SmallTalk
environments and to computer algebra systems with GUIs - and we
will present several tests that should help with troubleshooting.
2. Low-level tests
Before we start the theory please try these low-level tests.
2.1. Preparation
Have have to make sure that:
1) "eev-channel.el" has been loaded,
2) the "$EEVDIR/eegchannel" script exists and is executable,
3) we have expect installed - eegchannel depends on it,
4) the temporary directory "$EEVTMPDIR/" exists.
Here is an e-script for that:
(add-to-list 'load-path (ee-expand "$EEVDIR"))
(require 'eev-channel)
* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
sudo apt-get install expect
echo $EEVDIR
cd $EEVDIR
pwd
wget -nc http://anggtwu.net/eev-current/eegchannel
chmod 755 eegchannel
ls -lAF $EEVDIR/eegchannel
expect -v
$EEVDIR/eegchannel A echo ok
echo $EEVTMPDIR
mkdir -p $EEVTMPDIR/
# (find-eev "eegchannel")
2.2. Test eegchannel
In this test we create a window setting like this,
______________________
| | |
| | shell |
| this |___________|
| intro | |
| | shell 2 |
|__________|___________|
and then:
1) we run "eegchannel A python" at the lower shell. This runs
a python interpreter "listening on channel A";
2) we use the top shell to send the lines "print(2+3)" and
"exit()" "through the channel A". In low-level terms
this means that for each line
a) we save it into the file "$EEVTMPDIR/eeg.A.str",
b) we send a signal SIGUSR1 to the process -
"eegchannel" - whose PID is stored in the file
"$EEVTMPDIR/eeg.A.pid".
c) When the eegchannel listening on the channel A receives
a SIGUSR1 it sends the line in "$EEVTMPDIR/eeg.A.str"
to the process that it controls (that is "python") "as
if the user had typed it".
Here is the demo. Run it with <F8>s:
* (find-3EE '(eepitch-shell) '(eepitch-shell2))
* (find-3ee '(eepitch-shell) '(eepitch-shell2))
* (eepitch-shell)
# Optional clean-up:
ls -lAF $EEVTMPDIR/eeg.A.*
rm -fv $EEVTMPDIR/eeg.A.*
* (eepitch-shell2)
# Start a python interpreter "listening on channel A":
$EEVDIR/eegchannel A python3
* (eepitch-shell)
# Check that eeg.A.pid exists and is very recent:
date
ls -lAF $EEVTMPDIR/eeg.A.*
# Send lines to eegchannel:
echo 'print(2+3)' > $EEVTMPDIR/eeg.A.str
kill -USR1 $(cat $EEVTMPDIR/eeg.A.pid)
echo 'exit()' > $EEVTMPDIR/eeg.A.str
kill -USR1 $(cat $EEVTMPDIR/eeg.A.pid)
2.3. Test `eechannel'
TODO: write this.
See:
(find-eev "eev-channels.el" "eechannel")
2.4. Test `eexterm'
TODO: write this.
See:
(find-eev "eev-channels.el" "eexterm")
3. The innards
Let's start with a detailed low-level view of of what we have
just summarized as to "save a command into a temporary file,
then send a signal to the external program etc etc".
Warning: this document is still VERY INCOMPLETE, and some parts
of it are just notes, drafts, and links that may not work for
you... =(
(find-eev "eegchannel")
(find-eev "anim/")
(find-eev "anim/channels.anim")
http://anggtwu.net/eev-current/eegchannel.html
4. The protocol, in diagrams
Here's a diagram that shows roughly what we have when X is
running both an Emacs and an xterm, each in a separate window.
Many details have been omitted - for examples, the real
communication happens through fifos and ptys, that are not shown
- but it's easy to build a complete diagram from this. The arrows
indicate flow of information.
keyboard mouse display
| | ^
v v |
+----------------------------+
| |
| X |
| |
+----------------------------+
key/mouse | ^ display key/mouse | ^ display
events v | commands events v | commands
+---------+ +---------+
| | | |
| emacs | | xterm |
| | | |
+---------+ +---------+
chars and | ^ chars and
signals v | signals
+---------+
| |
| sh |
| |
+---------+
To make the external shell at the right able to receive commands
from Emacs we will insert a program between the "xterm" and the
"sh" boxes - an Expect script called eechannel, that will
usually be totally transparent, in the sense that it will let all
the chars and signals that it receives pass through it without
changes.
The trick is that "eechannel" will also be "listening to
commands from the outside", according to the following protocol:
1) each instance of eechannel "listens" to a fixed, named
"channel"; for simplicity, let's suppose that this name is
"A".
2) When an eechannel receives a signal SIGUSR1 it reads a
string from the file "eech.A.str" and sends that to the
shell, as if the user had typed that.
3) To make it simpler to send the signal, when eechannel starts
up it saves its pid into the file "eech.A.pid".
That protocol can be depicted as the four horizontal arrows
below; the temporal order is from top to bottom.
+-------------+
| |
| xterm |
| |
+-------------+
+-----------+ | ^
| | --> eeg.A.str v |
| emacs | <-- eeg.A.pid +-------------+
| | -----------------> | |
+-----------+ eeg.A.str ---> | eechannel A |
| |
+-------------+
| ^
v |
+-------------+
| |
| sh |
| |
+-------------+
When Emacs wants to send a line, say, "cd /tmp/", to eechannel,
it does this:
1) "--> eeg.A.str " writes "cd /tmp/" into eech.A.str,
2) "<-- eeg.A.pid " reads eechannel's pid from eech.B.str,
3) "----------------->" sends a signal SIGUSR1 to that pid,
4) " eeg.A.str --->" ...and when eechannel receives a SIGUSR1
it reads the contents of eech.A.str and
sends that to its spawned shell.
Actually there's something else - how these programs are started.
If we run just "xterm", it behaves in its default way, and runs
a shell. But if we run
"xterm -e eechannel A /bin/sh"
then xterm runs "eechannel A /bin/sh" instead of just
"/bin/sh"; and "eechannel A /bin/sh" runs "/bin/sh".
Also, evaluating this
(find-bgprocess "xterm")
from Emacs runs an xterm, which runs a shell; evaluating either
of these sexps,
(find-bgprocess "xterm -e eechannel A /bin/sh")
(find-bgprocess "xterm -e eechannel A $SHELL")
runs an xterm, which runs the "eechannel" script, which runs a
shell. The sexp
(eexterm "A")
is a shorthand for the one using "$SHELL". Also, note that
"eechannel A ..." saves its pid into "eech.A.pid".
The diagram that shows what happens when we run `(eexterm "A")'
is this one, below - note that the four arrows of the sending
protocol are not shown.
+------------+
| |
| X |
| |
+------------+
/ ^ \ ^
v / v \
+-----------+ +-------------+
| | initiates | |
| emacs |:::::::::::>| xterm |
| | | |
+-----------+ +-------------+
:: | ^
\/ v |
+-------------+
| |
eeg.A.pid <-- | eechannel A |
| |
+-------------+
:: | ^
\/ v |
+-------------+
| |
| sh |
| |
+-------------+
5. Downloading and testing eechannel
Here I'll suppose that the directory "~/bin/" exists and is in
your PATH. Run this to download the "eechannel" script and make
it executable:
* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
cd ~/bin/
# See: http://anggtwu.net/bin/eechannel.html
wget -n http://anggtwu.net/bin/eechannel
chmod 755 eechannel
Now let's test - from Emacs - if a local copy of "eechannel"
exists, is in your PATH, and can be executed (remember that it
needs Expect). Calling "eechannel" with not enough arguments
should yield a nice error message.
(find-fline "~/bin/eechannel")
(find-sh "~/bin/eechannel")
(find-sh "eechannel")
It uses the environment variable EEVTMPDIR to decide where the
temporary files - ee.CHANNELAME.pid, ee.CHANNELNAME.str - will
be, so let's check that this directory exists:
(getenv "EEVTMPDIR")
(find-fline "$EEVTMPDIR/")
Running eechannel with a first argument "-v" should show a lot
of info, and then save the pid at eech.CHANNELAME.pid and run the
given command. Let's try with a command that exits immediately.
(find-sh "eechannel -v A /bin/true")
(find-fline "$EEVTMPDIR/" "eech.A.pid")
Now let's verify - using just eepitch, without xterm at this
moment - whether eechannel is being able to receive signals. In
the eepitch script below, two `(find-sh0 "kill ...")'s should
each make the controlled program receive a command - at the first
"kill" an "echo 2", at the second an "echo 3".
* (eepitch-comint "A" "eechannel -v A /bin/sh")
* (eepitch-kill)
* (eepitch-comint "A" "eechannel -v A /bin/sh")
echo 1
* (find-sh0 " cat $EEVTMPDIR/eech.A.pid")
* (find-sh0 "echo 'echo 2' > $EEVTMPDIR/eech.A.str")
* (find-sh0 " cat $EEVTMPDIR/eech.A.str")
* (find-sh0 "kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)")
*
* (find-sh0 "echo 'echo 3' > $EEVTMPDIR/eech.A.str")
* (find-sh0 "kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)")
echo 4
If the eepitched shell did run "echo 1", "echo 2", "echo
3", "echo 4", then things are working - "echo 1" and "echo
4" were sent through eepitch, but "echo 3" and "echo 4" were
sent though channels.
Now let's check if we can run an xterm, and if it can run an
eechannel-ed shell instead of a plain shell. Check if the second
sexp above starts an xterm, displays the info from "eechannel
-v", and then runs a shell:
(find-bgprocess "xterm")
(find-bgprocess "xterm -e eechannel -v A $SHELL")
(find-bgprocess "xterm -e eechannel A $SHELL")
if that worked, run the four sexps below with <f8>,
* (find-sh0 "echo 'echo 1' > $EEVTMPDIR/eech.A.str")
* (find-sh0 "kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)")
* (find-sh0 "echo 'echo 2' > $EEVTMPDIR/eech.A.str")
* (find-sh0 "kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)")
and check if the eechannel-ed shell in the xterm has received the
commands "echo 1" and "echo 2". If it did, try the
higher-level version below - but use <f9>s on each line instead
of the <f8>s:
* (eexterm "A")
echo 3
echo 4
If that worked, we're done. =)
6. Several xterms
http://anggtwu.net/eev-current/anim/channels.anim.html
* (eexterm "A")
* (eexterm "B")
# listen on port 1234
netcat -l -p 1234
* (eexterm "A")
# Send things to port 1234 (on localhost)
{
echo hi
sleep 1
echo bye
sleep 1
} | netcat -q O localhost 1234
[NOT DONE YET. The rest is (recyclable) garbage.]
(Old stuff:)
emacs runs: (find-bgprocess "xterm -T 'channel A' -e eegchannel A /bin/sh")
xterm runs: eegchannel A /bin/sh
eegchannel saves its pid at ~/.eev/eeg.A.pid and runs: /bin/sh
At this point the xterm is running a shell that is "listening on
channel A"; eegchannel pretends to be transparent and passes all
characters and signals in the vertical arrows transparently - but when
it receives a certain signal (a SIGUSR1) it reads the contents from
the file ~/.eev/eeg.A.str and passes it to the shell, as if those
characters were coming from the xterm - i.e., as if the used had typed
them.
Here are the details of this "protocol":
when we type F9 on a line containing "echo foo",
emacs saves the string "echo foo\n" into ~/.eev/A.str,
emacs reads the pid of eegchannel from ~/.eev/eeg.A.pid (say, "1022"),
emacs runs "kill -USR1 1022",
eegchannel reads the string from ~/.eev/A.str, and sends it to the shell.
NOTE: one frequent question is: "why are you using two normal files
and SIGUSR1s for the communication between emacs and eegchannel,
instead of making them talk through a fifo?" - the answer is: try to
explain the details of fifos - including creation - to someone who
knows little about the inner workings of a *NIX kernel and who is
uncomfortable to accept another kind of black box... The way with two
files and SIGUSR1s is simpler, works well enough, and I've been able
to write all the code for it in a few hours - and I still don't know
enough about fifos to implement a fifo version of this.
and another one, that was mostly used to control external
programs running in dedicated xterms. You can see an animation
demonstrating it - and an explanation of what each line does -
here:
http://anggtwu.net/eev-current/anim/channels.anim.html
http://anggtwu.net/eev-current/doc/shot-f9.png
How to set it up
[To be written]
ssh edrx@other.machine
eegchannel A ssh edrx@other.machine
(find-prepared-intro "\n`ee'\n")
(find-eev "anim/channels.anim")