README
1This is gnuserv 3.12 for GNU Emacs, available via:
2
3 http://meltin.net/hacks/emacs/
4
5Introduction
6------------
7
8gnuserv allows you to attach to an already running Emacs. This allows
9external programs to make use of Emacs' editing capabilities. It is
10like GNU Emacs' emacsserver/server.el, but has many more features.
11
12This is a standalone release of gnuserv for GNU Emacs, requiring
13compatibility code (gnuserv-compat.el) to make it work. It has been
14tested under GNU Emacs 19.34 - 20.7. Note that this version of
15gnuserv requires the newer style of Emacs customisation stuff that
16comes with Emacs 20 or higher. It might work with the unbundled
17version of custom for Emacs 19
18(http://www.dina.kvl.dk/~abraham/custom/). Also, a hack has been
19added to do a simple emulation of the customisation stuff under 19.34
20if custom.el can't be loaded.
21
22Note that creating a frame on a tty (via "gnuclient -nw ...") does not
23work. GNU Emacs doesn't support this functionality.
24
25Note that if you run XEmacs then you do not need this package, because
26gnuserv comes bundled with XEmacs. Also, if you have XEmacs
27installed, but want to use gnuserv under GNU Emacs (for some strange
28reason) then all you need is gnuserv-compat.el (and probably
29devices.el). You can just make a link from your GNU Emacs site-lisp
30directory to gnuserv.el in your XEmacs installation.
31
32Origins
33-------
34
35* gnuserv.el, supporting C programs and manual page, from XEmacs
36 21.2.43 (http://www.xemacs.org/).
37
38* devices.el is from the w3 4.0pre.39 distribution.
39
40* Most of the other stuff (configure/make stuff, installation
41 utilities, README.orig) is from Noah Friedman's fgnuserv package. I
42 removed a patch for Emacs 18 from the distribution because it'd be
43 quite difficult to make this version of gnuserv.el work with Emacs
44 18.
45
46What did I do?
47
48* Added gnuserv-compat.el to make gnuserv.el work with GNU Emacs.
49
50* Tweaked the configure/make stuff to make it work for the this
51 version of gnuserv. Added some configure options.
52
53* Minor changes/bug fixes to gnuclient.c, gnuslib.c and gnuserv.h:
54
55 - A tweak of the #include for config.h in gnuserv.h.
56
57 - Checks added to gnuserv.h for Internet domain sockets, Unix domain
58 sockets and SYSV IPC, as handled by configure. Removed choice of
59 default, since people shouldn't get things that they've configured
60 out.
61
62 - Slight modifications to gnuclient.c and gnuslib.c so that they
63 compile if only one of INTERNET_DOMAIN_SOCKETS,
64 UNIX_DOMAIN_SOCKETS and SYSV_IPC is defined.
65
66Installation
67------------
68
69Simple instructions:
70
71 ./configure
72 make
73 make install
74
75This configures the gnuserv compilation process for your system,
76compiles C programs, and installs binaries, scripts and manual pages
77(under /usr/local). Please see INSTALL for details of how to
78customise things like installation paths.
79
80The current installation process doesn't install the elisp files,
81although it does byte-compile them. You should copy them to your
82site-lisp directory. Then add an autoload, as described in
83gnuserv-compat.el, to your ~/.emacs file or your
84site-lisp/site-start.el file.
85
86Known problems
87--------------
88
89* Linking problems:
90
91 If you experience unresolved symbols at link time this may be
92 because you have installed GCC but are using the native linker that
93 was bundled with your operating system (instead of the one from GNU
94 binutils). This means that GCC's C preprocessor is able to find
95 header files in /usr/local/include, but the native linker is not
96 able to find libraries in /usr/local/lib.
97
98 A possible solution to this is to set LDFLAGS to "-L/usr/local/lib"
99 before running "./configure". If you're using a Bourne-compatible
100 shell, you can do:
101
102 LDFLAGS="-L/usr/local/lib" ./configure [options]
103
104 Alternatively, something like:
105
106 env LDFLAGS="-L/usr/local/lib" ./configure [options]
107
108 works with many systems/shells.
109
110 The alternative would be to make major modifications to
111 configure.in.
112
113* If you use SSH to connect to a machine that is already running
114 Emacs/gnuserv, and then try to connect using gnuclient, Emacs may
115 exit or behave weirdly. This is an Emacs/X problem, since Emacs
116 can't find SSH's temporary cookie file. The whole situation can't
117 be easily fixed in Emacs or gnuserv, but Emacs should not crash.
118
119 A work-around that allows you to connect is to do this:
120
121 xauth extract - $DISPLAY | xauth -f .Xauthority merge -
122
123 in the SSH session. This puts the cookie for the SSH session's
124 display into the standard .Xauthority file so Emacs/X can find it.
125
126 Thanks to Martin Thornquist <martint@ifi.uio.no> for providing this
127 work-around. He got it from Frode Vatvedt Fjeld <frodef@acm.org>.
128
129* If you've done the above and used gnuserv via SSH, then you probably
130 can't close the SSH session. This is because Emacs doesn't
131 disconnect from a display when it has no more frames open on it.
132 The following very, very gross hack seems to do the trick:
133
134 (defun x-close-connection-if-no-frames (display)
135 "Close an open connection to DISPLAY if DISPLAY has no frames."
136
137 (if (and
138 (member display (x-display-list))
139 (not
140 (eval (cons 'or
141 (mapcar
142 '(lambda (f) (equal (frame-parameter f 'display)
143 display))
144 (frame-list))))))
145 (x-close-connection display)))
146
147 (defadvice delete-frame (around
148 x-close-connection-delete-frame
149 first
150 nil
151 activate)
152 (let ((display (frame-parameter frame 'display)))
153 ad-do-it
154 (x-close-connection-if-no-frames display)))
155
156dtemacs
157-------
158
159Also available is a script called dtemacs. This can be used to invoke
160an editing session within Emacs and has been used to integrate Emacs
161into desktop environments like CDE or KDE. If Emacs can not be
162contacted using gnuserv, Emacs is executed and left iconified. Either
163way, a new frame is opened to edit the specified files.
164
165Get it from:
166
167 http://meltin.net/hacks/emacs/src/dtemacs
168
169I've told Gnome to use dtemacs as the default editor. Previously, I
170told KDE to use dtemacs for various types of text and program files.
171
172TODO
173----
174
175Not all of the configure options are defined or work properly:
176
177* I don't know how to define SOCKADDR_SUN_LEN and BROKEN_INET_ADDR.
178
179Maintenance
180-----------
181
182Please report problems about the following to me:
183
184* gnuserv-compat.el (elisp errors from gnuserv.el in GNU Emacs)
185
186* the configuration & installation procedure
187
188* total failures to get this version of gnuserv to do anything!
189
190If you're sure you have found a bug in the C code (not likely to be
191caused by my changes) or gnuserv.el then, of course, feel free to
192contact the maintainers of those components. If you're not sure then
193please check with me. I'd hate to bother other people with problems
194that I've created!
195
196My plan it to grab each new version of gnuserv as it appears, package
197it and release it. Please feel free to make suggestions, but remember
198that I'm trying to change as little of the original gnuserv code as
199possible. My goal is to just to make new versions of gnuserv work
200with GNU Emacs.
201
202Martin Schwenke <martin@meltin.net>
203http://meltin.net/people/martin/
204