<< | Page list | >>
The LyXServer communicates with LyX via named pipes.
The LyXServer is a method implemented in LyX that enables other programs to communicate with LyX, invoke LyX commands, and retrieve information about LyX's internal state. Why would you want to do that? Well for example when citing you might want to switch to your reference management software (such as JabRef) and check you have the right reference, or indeed all the relevant references, and then push them to the insertion point in LyX. Another example would be opening a file in an already running instance of LyX (see this page).
The following description is only intended for advanced users, but they might find it useful.
The LyXServer uses a pair of named pipes. These are usually located in your home directory and have the names
According to this thread on the ubuntu forums JabRef expects the pipe to be at
LyX adds the '.in' and '.out' suffixes while creating the pipes. The above setting also has the effect of activating the LyXServer. If one of the pipes already exists, LyX will assume that another LyX process is already running and will not start the server. To have several LyX processes with servers at the same time, you have to change the configuration between the starts of the programs.
If you are developing a client program, you might find it useful to enable debugging information from the LyXServer. Do this by starting LyX as
Warning: if LyX crashes, it may not manage to remove the pipes; in this case you must remove them manually. If LyX starts and the pipes exist already, it will not start any server.
Other than this, there are a few points to consider:
You can find some complete example clients written in C, tcl and perl in the source distribution at development/lyxserver/.
There is also a client written in python at Tools.PyClient
As of LyX 1.6.5, the lyxserver also works on Windows. See the Additional Features manual, chapter 4, for further details. On LyX 1.6.4 and earlier versions, the lyxserver does not work on Windows (except Cygwin), as it was implemented in a UNIX-specific way. Lyxserver does not use normal files but uses Windows' notation (
To set up the LyXServer, set the named pipe in Menu→Tools→Preferences→Paths→LyxServer path to
LyX adds the '.in' and '.out' suffixes while creating the pipes when LyX is launched. The above setting also has the effect of activating the LyXServer. If one of the pipes already exists, LyX will assume that another LyX process is already running and will not start the server. To have several LyX processes with servers at the same time, you have to change the configuration between the starts of the programs.
Client applications, such as JabRef, can be used to push citations to LyX via the LyXServer. In Options→Preferences→External Program→Setting for insert selected citations into Lyx/Kile, there's a widget to configure the lyxserver. Input the string
To issue a LyX call, the client writes a line of ASCII text into the input pipe. This line has the following format:
The answer from LyX will arrive in the output pipe and be of the form
where clientname and function are just echoed from the command request, while data is more or less useful information filled according to how the command execution worked out. Some commands will return information about the internal state of LyX, such as "font-state", while other will return an empty data-response. This means that the command execution went fine.
In case of errors, the response from LyX will have this form
where the error message should contain an explanation of why the command failed.
echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
read a <~/.lyxpipe.out
LyX can notify clients of events going on asynchronously. Currently it will only do this if the user binds a key sequence with the function "notify". The format of the string LyX sends is as follows:
where key-sequence is the printed representation of the key sequence that was actually typed by the user.
This mechanism can be used to extend LyX's command set and implement macros: bind some key sequence to "notify", start a client that listens on the out pipe, dispatches the command according to the sequence and starts a function that may use LyX calls and LyX requests to issue a command or a series of commands to LyX.
LyX implements a simple protocol that can be used for session management. All messages are of the form
where protocol message can be "hello" or "bye". If "hello" is received from a client, LyX will report back to inform the client that it's listening to it's messages, while "bye" sent from LyX will inform clients that LyX is closing.