nixos/modules/services/editors/emacs.md

   1 # Emacs {#module-services-emacs}
   2
   3 <!--
   4     Documentation contributors:
   5       Damien Cassou @DamienCassou
   6       Thomas Tuegel @ttuegel
   7       Rodney Lorrimar @rvl
   8       Adam Hoese @adisbladis
   9   -->
  10
  11 [Emacs](https://www.gnu.org/software/emacs/) is an
  12 extensible, customizable, self-documenting real-time display editor — and
  13 more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
  14 programming language with extensions to support text editing.
  15
  16 Emacs runs within a graphical desktop environment using the X Window System,
  17 but works equally well on a text terminal. Under
  18 macOS, a "Mac port" edition is available, which
  19 uses Apple's native GUI frameworks.
  20
  21 Nixpkgs provides a superior environment for
  22 running Emacs. It's simple to create custom builds
  23 by overriding the default packages. Chaotic collections of Emacs Lisp code
  24 and extensions can be brought under control using declarative package
  25 management. NixOS even provides a
  26 {command}`systemd` user service for automatically starting the Emacs
  27 daemon.
  28
  29 ## Installing Emacs {#module-services-emacs-installing}
  30
  31 Emacs can be installed in the normal way for Nix (see
  32 [](#sec-package-management)). In addition, a NixOS
  33 *service* can be enabled.
  34
  35 ### The Different Releases of Emacs {#module-services-emacs-releases}
  36
  37 Nixpkgs defines several basic Emacs packages.
  38 The following are attributes belonging to the {var}`pkgs` set:
  39
  40   {var}`emacs`
  41   : The latest stable version of Emacs using the [GTK 2](http://www.gtk.org)
  42     widget toolkit.
  43
  44   {var}`emacs-nox`
  45   : Emacs built without any dependency on X11 libraries.
  46
  47   {var}`emacsMacport`
  48   : Emacs with the "Mac port" patches, providing a more native look and
  49     feel under macOS.
  50
  51 If those aren't suitable, then the following imitation Emacs editors are
  52 also available in Nixpkgs:
  53 [Zile](https://www.gnu.org/software/zile/),
  54 [mg](http://homepage.boetes.org/software/mg/),
  55 [Yi](http://yi-editor.github.io/),
  56 [jmacs](https://joe-editor.sourceforge.io/).
  57
  58 ### Adding Packages to Emacs {#module-services-emacs-adding-packages}
  59
  60 Emacs includes an entire ecosystem of functionality beyond text editing,
  61 including a project planner, mail and news reader, debugger interface,
  62 calendar, and more.
  63
  64 Most extensions are gotten with the Emacs packaging system
  65 ({file}`package.el`) from
  66 [Emacs Lisp Package Archive (ELPA)](https://elpa.gnu.org/),
  67 [MELPA](https://melpa.org/),
  68 [MELPA Stable](https://stable.melpa.org/), and
  69 [Org ELPA](http://orgmode.org/elpa.html). Nixpkgs is
  70 regularly updated to mirror all these archives.
  71
  72 Under NixOS, you can continue to use
  73 `package-list-packages` and
  74 `package-install` to install packages. You can also
  75 declare the set of Emacs packages you need using the derivations from
  76 Nixpkgs. The rest of this section discusses declarative installation of
  77 Emacs packages through nixpkgs.
  78
  79 The first step to declare the list of packages you want in your Emacs
  80 installation is to create a dedicated derivation. This can be done in a
  81 dedicated {file}`emacs.nix` file such as:
  82
  83 ::: {.example #ex-emacsNix}
  84 ### Nix expression to build Emacs with packages (`emacs.nix`)
  85
  86 ```nix
  87 /*
  88 This is a nix expression to build Emacs and some Emacs packages I like
  89 from source on any distribution where Nix is installed. This will install
  90 all the dependencies from the nixpkgs repository and build the binary files
  91 without interfering with the host distribution.
  92
  93 To build the project, type the following from the current directory:
  94
  95 $ nix-build emacs.nix
  96
  97 To run the newly compiled executable:
  98
  99 $ ./result/bin/emacs
 100 */
 101
 102 # The first non-comment line in this file indicates that
 103 # the whole file represents a function.
 104 { pkgs ? import <nixpkgs> {} }:
 105
 106 let
 107   # The let expression below defines a myEmacs binding pointing to the
 108   # current stable version of Emacs. This binding is here to separate
 109   # the choice of the Emacs binary from the specification of the
 110   # required packages.
 111   myEmacs = pkgs.emacs;
 112   # This generates an emacsWithPackages function. It takes a single
 113   # argument: a function from a package set to a list of packages
 114   # (the packages that will be available in Emacs).
 115   emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages;
 116 in
 117   # The rest of the file specifies the list of packages to install. In the
 118   # example, two packages (magit and zerodark-theme) are taken from
 119   # MELPA stable.
 120   emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
 121     magit          # ; Integrate git <C-x g>
 122     zerodark-theme # ; Nicolas' theme
 123   ])
 124   # Two packages (undo-tree and zoom-frm) are taken from MELPA.
 125   ++ (with epkgs.melpaPackages; [
 126     undo-tree      # ; <C-x u> to show the undo tree
 127     zoom-frm       # ; increase/decrease font size for all buffers %lt;C-x C-+>
 128   ])
 129   # Three packages are taken from GNU ELPA.
 130   ++ (with epkgs.elpaPackages; [
 131     auctex         # ; LaTeX mode
 132     beacon         # ; highlight my cursor when scrolling
 133     nameless       # ; hide current package name everywhere in elisp code
 134   ])
 135   # notmuch is taken from a nixpkgs derivation which contains an Emacs mode.
 136   ++ [
 137     pkgs.notmuch   # From main packages set
 138   ])
 139 ```
 140 :::
 141
 142 The result of this configuration will be an {command}`emacs`
 143 command which launches Emacs with all of your chosen packages in the
 144 {var}`load-path`.
 145
 146 You can check that it works by executing this in a terminal:
 147 ```ShellSession
 148 $ nix-build emacs.nix
 149 $ ./result/bin/emacs -q
 150 ```
 151 and then typing `M-x package-initialize`. Check that you
 152 can use all the packages you want in this Emacs instance. For example, try
 153 switching to the zerodark theme through `M-x load-theme <RET> zerodark <RET> y`.
 154
 155 ::: {.tip}
 156 A few popular extensions worth checking out are: auctex, company,
 157 edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
 158 and yasnippet.
 159 :::
 160
 161 The list of available packages in the various ELPA repositories can be seen
 162 with the following commands:
 163 ::: {.example #module-services-emacs-querying-packages}
 164 ### Querying Emacs packages
 165
 166 ```
 167 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages
 168 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages
 169 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages
 170 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages
 171 ```
 172 :::
 173
 174 If you are on NixOS, you can install this particular Emacs for all users by
 175 putting the `emacs.nix` file in `/etc/nixos` and adding it to the list of
 176 system packages (see [](#sec-declarative-package-mgmt)). Simply modify your
 177 file {file}`configuration.nix` to make it contain:
 178 ::: {.example #module-services-emacs-configuration-nix}
 179 ### Custom Emacs in `configuration.nix`
 180
 181 ```nix
 182 {
 183  environment.systemPackages = [
 184    # [...]
 185    (import ./emacs.nix { inherit pkgs; })
 186   ];
 187 }
 188 ```
 189 :::
 190
 191 In this case, the next {command}`nixos-rebuild switch` will take
 192 care of adding your {command}`emacs` to the {var}`PATH`
 193 environment variable (see [](#sec-changing-config)).
 194
 195 <!-- fixme: i think the following is better done with config.nix
 196 https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
 197 -->
 198
 199 If you are not on NixOS or want to install this particular Emacs only for
 200 yourself, you can do so by putting `emacs.nix` in `~/.config/nixpkgs` and
 201 adding it to your {file}`~/.config/nixpkgs/config.nix` (see
 202 [Nixpkgs manual](https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides)):
 203 ::: {.example #module-services-emacs-config-nix}
 204 ### Custom Emacs in `~/.config/nixpkgs/config.nix`
 205
 206 ```nix
 207 {
 208   packageOverrides = super: let self = super.pkgs; in {
 209     myemacs = import ./emacs.nix { pkgs = self; };
 210   };
 211 }
 212 ```
 213 :::
 214
 215 In this case, the next `nix-env -f '<nixpkgs>' -iA
 216 myemacs` will take care of adding your emacs to the
 217 {var}`PATH` environment variable.
 218
 219 ### Advanced Emacs Configuration {#module-services-emacs-advanced}
 220
 221 If you want, you can tweak the Emacs package itself from your
 222 {file}`emacs.nix`. For example, if you want to have a
 223 GTK 3-based Emacs instead of the default GTK 2-based binary and remove the
 224 automatically generated {file}`emacs.desktop` (useful if you
 225 only use {command}`emacsclient`), you can change your file
 226 {file}`emacs.nix` in this way:
 227
 228 ::: {.example #ex-emacsGtk3Nix}
 229 ### Custom Emacs build
 230
 231 ```nix
 232 { pkgs ? import <nixpkgs> {} }:
 233 let
 234   myEmacs = (pkgs.emacs.override {
 235     # Use gtk3 instead of the default gtk2
 236     withGTK3 = true;
 237     withGTK2 = false;
 238   }).overrideAttrs (attrs: {
 239     # I don't want emacs.desktop file because I only use
 240     # emacsclient.
 241     postInstall = (attrs.postInstall or "") + ''
 242       rm $out/share/applications/emacs.desktop
 243     '';
 244   });
 245 in [ /* ... */ ]
 246 ```
 247 :::
 248
 249 After building this file as shown in [](#ex-emacsNix), you
 250 will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
 251
 252 ## Running Emacs as a Service {#module-services-emacs-running}
 253
 254 NixOS provides an optional
 255 {command}`systemd` service which launches
 256 [Emacs daemon](https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html)
 257 with the user's login session.
 258
 259 *Source:* {file}`modules/services/editors/emacs.nix`
 260
 261 ### Enabling the Service {#module-services-emacs-enabling}
 262
 263 To install and enable the {command}`systemd` user service for Emacs
 264 daemon, add the following to your {file}`configuration.nix`:
 265 ```nix
 266 {
 267   services.emacs.enable = true;
 268 }
 269 ```
 270
 271 The {var}`services.emacs.package` option allows a custom
 272 derivation to be used, for example, one created by
 273 `emacsWithPackages`.
 274
 275 Ensure that the Emacs server is enabled for your user's Emacs
 276 configuration, either by customizing the {var}`server-mode`
 277 variable, or by adding `(server-start)` to
 278 {file}`~/.emacs.d/init.el`.
 279
 280 To start the daemon, execute the following:
 281 ```ShellSession
 282 $ nixos-rebuild switch  # to activate the new configuration.nix
 283 $ systemctl --user daemon-reload        # to force systemd reload
 284 $ systemctl --user start emacs.service  # to start the Emacs daemon
 285 ```
 286 The server should now be ready to serve Emacs clients.
 287
 288 ### Starting the client {#module-services-emacs-starting-client}
 289
 290 Ensure that the Emacs server is enabled, either by customizing the
 291 {var}`server-mode` variable, or by adding
 292 `(server-start)` to {file}`~/.emacs`.
 293
 294 To connect to the Emacs daemon, run one of the following:
 295 ```
 296 emacsclient FILENAME
 297 emacsclient --create-frame  # opens a new frame (window)
 298 emacsclient --create-frame --tty  # opens a new frame on the current terminal
 299 ```
 300
 301 ### Configuring the {var}`EDITOR` variable {#module-services-emacs-editor-variable}
 302
 303 <!--<title>{command}`emacsclient` as the Default Editor</title>-->
 304
 305 If [](#opt-services.emacs.defaultEditor) is
 306 `true`, the {var}`EDITOR` variable will be set
 307 to a wrapper script which launches {command}`emacsclient`.
 308
 309 Any setting of {var}`EDITOR` in the shell config files will
 310 override {var}`services.emacs.defaultEditor`. To make sure
 311 {var}`EDITOR` refers to the Emacs wrapper script, remove any
 312 existing {var}`EDITOR` assignment from
 313 {file}`.profile`, {file}`.bashrc`,
 314 {file}`.zshenv` or any other shell config file.
 315
 316 If you have formed certain bad habits when editing files, these can be
 317 corrected with a shell alias to the wrapper script:
 318 ```
 319 alias vi=$EDITOR
 320 ```
 321
 322 ### Per-User Enabling of the Service {#module-services-emacs-per-user}
 323
 324 In general, {command}`systemd` user services are globally enabled
 325 by symlinks in {file}`/etc/systemd/user`. In the case where
 326 Emacs daemon is not wanted for all users, it is possible to install the
 327 service but not globally enable it:
 328 ```nix
 329 {
 330   services.emacs.enable = false;
 331   services.emacs.install = true;
 332 }
 333 ```
 334
 335 To enable the {command}`systemd` user service for just the
 336 currently logged in user, run:
 337 ```
 338 systemctl --user enable emacs
 339 ```
 340 This will add the symlink
 341 {file}`~/.config/systemd/user/emacs.service`.
 342
 343 ## Configuring Emacs {#module-services-emacs-configuring}
 344
 345 If you want to only use extension packages from Nixpkgs, you can add
 346 `(setq package-archives nil)` to your init file.
 347
 348 After the declarative Emacs package configuration has been tested,
 349 previously downloaded packages can be cleaned up by removing
 350 {file}`~/.emacs.d/elpa` (do make a backup first, in case you
 351 forgot a package).
 352
 353 <!--
 354       todo: is it worth documenting customizations for
 355       server-switch-hook, server-done-hook?
 356   -->
 357
 358 ### A Major Mode for Nix Expressions {#module-services-emacs-major-mode}
 359
 360 Of interest may be {var}`melpaPackages.nix-mode`, which
 361 provides syntax highlighting for the Nix language. This is particularly
 362 convenient if you regularly edit Nix files.
 363
 364 ### Accessing man pages {#module-services-emacs-man-pages}
 365
 366 You can use `woman` to get completion of all available
 367 man pages. For example, type `M-x woman <RET> nixos-rebuild <RET>.`
 368