Difference between revisions of "Emacs server"

From WikEmacs
Jump to navigation Jump to search
(→‎OS X: launch configuration)
 
(29 intermediate revisions by 12 users not shown)
Line 1: Line 1:
Emacs includes an optional client-server architecture.
+
Emacs includes an optional client-server architecture. The benefit of running emacs in server mode is that new client instances can be started up instantaneously.  If you have 100+ packages and starting Emacs usually takes several seconds, using server mode creates a much more streamlined workflow without sacrificing customization functionality.
  
 
== Starting the Server ==
 
== Starting the Server ==
 +
 
=== With <code>server-start</code> ===
 
=== With <code>server-start</code> ===
To start a server in an existing Emacs session, run <code>server-start</code>. A server started in this manner will close when the last visible Emacs frame closes. If you want Emacs to automatically run a server on startup, it makes sense to add <code>server-start</code> to your configuration file somewhere.
+
To start a server in an existing Emacs session, run {{Command|server-start}}. A server started in this manner will close when the last visible Emacs frame closes. If you want Emacs to automatically run a server on startup, add the following to your configuration file.
 +
 
 +
<syntaxhighlight lang="lisp">
 +
(server-start)
 +
</syntaxhighlight>
 +
 
 
=== With <tt>--daemon</tt> ===
 
=== With <tt>--daemon</tt> ===
Emacs 24 and higher provide the <tt>--daemon</tt> command-line argument, which will cause Emacs to immediately start a server and fork into the background. A server started in this manner is fully daemonized and will remain running even with no visible Emacs frames and after its parent terminal has closed (for example, after an SSH session has disconnected).
+
Emacs 23 and higher provide the <tt>--daemon</tt> command-line argument, which will cause Emacs to immediately start a server and fork into the background. A server started in this manner is fully daemonized and will remain running even with no visible Emacs frames and after its parent terminal has closed (for example, after an SSH session has disconnected).  
  
 
Note that, if using <tt>--daemon</tt>, your configuration file will be run while Emacs is still in a terminal. This may affect your theming if you usually use graphical Emacs.
 
Note that, if using <tt>--daemon</tt>, your configuration file will be run while Emacs is still in a terminal. This may affect your theming if you usually use graphical Emacs.
 +
 +
{{Note}}This option is not supported on [[Windows]].
  
 
== Using Clients ==
 
== Using Clients ==
Line 14: Line 22:
  
 
If the server was started using <tt>--daemon</tt>, you should run <tt>emacsclient -t</tt> or <tt>emacsclient -nc</tt> to create a visible frame to interact with.
 
If the server was started using <tt>--daemon</tt>, you should run <tt>emacsclient -t</tt> or <tt>emacsclient -nc</tt> to create a visible frame to interact with.
 +
== Finishing Up ==
  
== Finishing Up ==
+
Once you have finished with a buffer that was opened via <tt>emacsclient</tt> you should use the {{CommandKeys|C-x #|server-edit}} to properly close the loop. Killing the buffer normally will not send the signal to <tt>emacsclient</tt> that Emacs has finished with the file.
 +
 
 +
If you're in an Emacs session that was started using <tt>--daemon</tt>, {{Keys|C-x C-c}} will only close the frame that it was invoked in. It will also signal to the client that owns the frame that its editing job is done, so <tt>emacsclient -c</tt> or <tt>emacsclient -t</tt> as <tt>EDITOR</tt> will behave much like a full <tt>emacs</tt> or <tt>emacs -nw</tt>.
 +
 
 +
To entirely close a server started with <tt>--daemon</tt>, run {{Command|save-buffers-kill-emacs}} in a frame.
 +
= Adding To OS Startup =
 +
== Linux ==
 +
 
 +
Configuration through the init daemon <code>systemd</code> is the preferred method of starting Emacs at launch on most major distributions, including Debian, Ubuntu, Fedora, OpenSUSE, Arch, and derivatives.
 +
 
 +
To tell systemd to start Emacs on init, place the following script <code>emacsd.service</code> in your systemd user configuration folder, modifying the binary .  On Debian-based distributions, this file should be named <code>~/.config/systemd/user/emacsd.service</code>. 
 +
 
 +
[Unit]
 +
Description=Emacs: the extensible, self-documenting text editor
 +
Documentation=man:emacs(1) info:Emacs
 +
 +
 +
[Service]
 +
Type=forking
 +
ExecStart=/usr/bin/emacs --daemon
 +
ExecStop=/usr/bin/emacsclient --eval "(progn (setq kill-emacs-hook nil) (kill-emacs))"
 +
Restart=on-failure
 +
Environment=DISPLAY=:%i
 +
TimeoutStartSec=0
 +
 +
[Install]
 +
WantedBy=default.target
 +
 
 +
Enable the new module with <code>systemctl --user enable emacsd</code>; useful commands besides <code>enable</code> include <code>stop</code>, <code>kill</code> and <code>restart</code>. After running enable, the service will be enabled permanently.  You can use <code>disable</code> if you no longer want systemd to run an Emacs daemon.
 +
 
 +
A few parts of this script are not quite self-documenting.  Two are just technical: <code>Type</code> tells systemd it should expect <code>emacs --systemd</code> to fork a server process, and <code>Environment</code> sets an environment variable to ensure Emacs works properly with multiple X displays.  The Restart command asks systemd to restart Emacs whenever there is a nonzero exit code.  For example, if Emacs hangs in the middle of a loop and you kill it in a task manager or run <code>systemctl --user kill</code>, systemd will restart Emacs.  Alternative values you may want to use are <code>no</code> and <code>always</code>.  TimeoutStartSec=0 tells systemd it shouldn't worry about how long it takes Emacs to start.  Specifying a timeout might be useful if you occasionally break your Emacs init file.
 +
 
 +
Systemd will not know what to do if Emacs tries to ask for input before closing, for example, if Desktop mode prompts for confirmation before overwriting a desktop file.  If the simple <code>(progn)</code> script executed on ExecStop</code> is not suitable,  You may need to define your own command for a clean exit and call that function instead.
 +
 
 +
If systemd is not available on your distribution, you can add <code>/usr/bin/emacs --daemon</code> to your crontab. However using systemd is preferable because of the ability to easily configure Emacs to restart, and because the process will begin at boot, i.e. without depending on the <code>cron</code> process to start.
 +
 
 +
== OS X ==
 +
<code>launchd</code> is the OS X analog of <code>systemd</code> and can be configured just as easily. The following is a valid launchd file based on the <code>homebrew</code> installation of emacs, modified to work for <code>homebrew cask</code> and to have a proper <code>PATH</code> variable so emacs can actually call binaries:
 +
<source lang="xml">
 +
 
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<! DOCTYPE  plist  PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 +
<plist version="1.0">
 +
<dict>
 +
  <key>KeepAlive</key>
 +
  <true/>
 +
  <key>Label</key>
 +
  <string>homebrew.mxcl.emacs</string>
 +
  <key>ProgramArguments</key>
 +
  <array>
 +
    <string>/usr/local/bin/emacs</string>
 +
    <string>--fg-daemon</string>
 +
  </array>
 +
  <key>RunAtLoad</key>
 +
  <true/>
 +
  <key>EnvironmentVariables</key>
 +
  <dict>
 +
    <key>PATH</key>
 +
    <string>/usr/local/opt/openssl/bin:/usr/local/sbin:/Library/Frameworks/Python.framework/Versions/3.4/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin:/usr/local/MacGPG2/bin</string>
 +
  </dict>
 +
</dict>
 +
</plist>
  
Once you have finished with a buffer that was opened via <tt>emacsclient</tt> you should use the <code>C-x #</code> (<code>server-edit</code>) to properly close the loop. Killing the buffer normally will not send the signal to <tt>emacsclient</tt> that Emacs has finished with the file.
+
</source>
 +
Remove the space after the exclamation mark in the second line (for some reason this wiki will crash without it), adjust the <code>PATH</code> environment variable and the executable location as needed and place this file in <code>~/Library/LaunchAgents</code>, then activate it using <code>launchctl load -w ~/Library/LaunchAgents/&lt;filename&gt;</code>.
  
If you're in an Emacs session that was started using <tt>--daemon</tt>, <code>C-x C-c</code> will only close the frame that it was invoked in. It will also signal to the client that owns the frame that its editing job is done, so <tt>emacsclient -c</tt> or <tt>emacsclient -t</tt> as <tt>EDITOR</tt> will behave much like a full <tt>emacs</tt> or <tt>emacs -nw</tt>.
+
== MS Windows ==
 +
Open the startup folder by running the command <code>shell:startup</code> in a run dialog or by typing it in the Windows Explorer path bar. Place a shortcut to Emacs in this folder to run Emacs at boot. Change the target to <code>runemacs --daemon</code> to run start it in daemon mode. Please note, you need at least Emacs 25 in order to use daemon on Windows. The best option for more advanced Emacs daemon-mode configuration on Windows is still not settled, there is some discussion on the Emacs Wiki which could potentially be sifted through.
  
To close a server started with <tt>--daemon</tt> entirely, run <code>save-buffers-kill-emacs</tt> in a frame.
+
[[Category: Server]]

Latest revision as of 20:27, 26 October 2019

Emacs includes an optional client-server architecture. The benefit of running emacs in server mode is that new client instances can be started up instantaneously. If you have 100+ packages and starting Emacs usually takes several seconds, using server mode creates a much more streamlined workflow without sacrificing customization functionality.

Starting the Server

With server-start

To start a server in an existing Emacs session, run M-x server-start. A server started in this manner will close when the last visible Emacs frame closes. If you want Emacs to automatically run a server on startup, add the following to your configuration file.

(server-start)

With --daemon

Emacs 23 and higher provide the --daemon command-line argument, which will cause Emacs to immediately start a server and fork into the background. A server started in this manner is fully daemonized and will remain running even with no visible Emacs frames and after its parent terminal has closed (for example, after an SSH session has disconnected).

Note that, if using --daemon, your configuration file will be run while Emacs is still in a terminal. This may affect your theming if you usually use graphical Emacs.

Note Note: This option is not supported on Windows.

Using Clients

Once the server is started you may use the emacsclient command outside of Emacs to send a file to Emacs for editing, e.g. emacsclient ~/.emacs.d/init.el to modify your init file. On a GNU/Linux system it might be a good idea to set your EDITOR environment variable to emacsclient or emacsclient -t. Using emacsclient without any arguments will cause the calling process to simply pause and wait for the Emacs server to report that it's done editing. Using emacsclient -t will cause the calling process to put up a text-mode frame in the same terminal.

If the server was started using --daemon, you should run emacsclient -t or emacsclient -nc to create a visible frame to interact with.

Finishing Up

Once you have finished with a buffer that was opened via emacsclient you should use the [C-x #] (or M-x server-edit) to properly close the loop. Killing the buffer normally will not send the signal to emacsclient that Emacs has finished with the file.

If you're in an Emacs session that was started using --daemon, [C-x C-c] will only close the frame that it was invoked in. It will also signal to the client that owns the frame that its editing job is done, so emacsclient -c or emacsclient -t as EDITOR will behave much like a full emacs or emacs -nw.

To entirely close a server started with --daemon, run M-x save-buffers-kill-emacs in a frame.

Adding To OS Startup

Linux

Configuration through the init daemon systemd is the preferred method of starting Emacs at launch on most major distributions, including Debian, Ubuntu, Fedora, OpenSUSE, Arch, and derivatives.

To tell systemd to start Emacs on init, place the following script emacsd.service in your systemd user configuration folder, modifying the binary . On Debian-based distributions, this file should be named ~/.config/systemd/user/emacsd.service.

[Unit]
Description=Emacs: the extensible, self-documenting text editor
Documentation=man:emacs(1) info:Emacs


[Service]
Type=forking
ExecStart=/usr/bin/emacs --daemon
ExecStop=/usr/bin/emacsclient --eval "(progn (setq kill-emacs-hook nil) (kill-emacs))"
Restart=on-failure
Environment=DISPLAY=:%i
TimeoutStartSec=0

[Install]
WantedBy=default.target

Enable the new module with systemctl --user enable emacsd; useful commands besides enable include stop, kill and restart. After running enable, the service will be enabled permanently. You can use disable if you no longer want systemd to run an Emacs daemon.

A few parts of this script are not quite self-documenting. Two are just technical: Type tells systemd it should expect emacs --systemd to fork a server process, and Environment sets an environment variable to ensure Emacs works properly with multiple X displays. The Restart command asks systemd to restart Emacs whenever there is a nonzero exit code. For example, if Emacs hangs in the middle of a loop and you kill it in a task manager or run systemctl --user kill, systemd will restart Emacs. Alternative values you may want to use are no and always. TimeoutStartSec=0 tells systemd it shouldn't worry about how long it takes Emacs to start. Specifying a timeout might be useful if you occasionally break your Emacs init file.

Systemd will not know what to do if Emacs tries to ask for input before closing, for example, if Desktop mode prompts for confirmation before overwriting a desktop file. If the simple (progn) script executed on ExecStop is not suitable, You may need to define your own command for a clean exit and call that function instead.

If systemd is not available on your distribution, you can add /usr/bin/emacs --daemon to your crontab. However using systemd is preferable because of the ability to easily configure Emacs to restart, and because the process will begin at boot, i.e. without depending on the cron process to start.

OS X

launchd is the OS X analog of systemd and can be configured just as easily. The following is a valid launchd file based on the homebrew installation of emacs, modified to work for homebrew cask and to have a proper PATH variable so emacs can actually call binaries:

<?xml version="1.0" encoding="UTF-8"?>
<! DOCTYPE  plist  PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
 <dict>
   <key>KeepAlive</key>
   <true/>
   <key>Label</key>
   <string>homebrew.mxcl.emacs</string>
   <key>ProgramArguments</key>
   <array>
     <string>/usr/local/bin/emacs</string>
     <string>--fg-daemon</string>
   </array>
   <key>RunAtLoad</key>
   <true/>
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
     <string>/usr/local/opt/openssl/bin:/usr/local/sbin:/Library/Frameworks/Python.framework/Versions/3.4/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin:/usr/local/MacGPG2/bin</string>
   </dict>
 </dict>
</plist>

Remove the space after the exclamation mark in the second line (for some reason this wiki will crash without it), adjust the PATH environment variable and the executable location as needed and place this file in ~/Library/LaunchAgents, then activate it using launchctl load -w ~/Library/LaunchAgents/<filename>.

MS Windows

Open the startup folder by running the command shell:startup in a run dialog or by typing it in the Windows Explorer path bar. Place a shortcut to Emacs in this folder to run Emacs at boot. Change the target to runemacs --daemon to run start it in daemon mode. Please note, you need at least Emacs 25 in order to use daemon on Windows. The best option for more advanced Emacs daemon-mode configuration on Windows is still not settled, there is some discussion on the Emacs Wiki which could potentially be sifted through.