From 6711e62d51a014d24eb1ec6313e1facf94bb8498 Mon Sep 17 00:00:00 2001 From: Rodney Lorrimar Date: Sat, 25 Jun 2016 23:19:27 +0100 Subject: [PATCH] nixos manual: add Emacs section (fixes #13217) In light of Emacs packaging improvements such as those mentioned in #11503, and with the addition of a systemd service (#15807 and #16356), and considering that the wiki page is completely out of date (#13217), it seems that some documentation is in order. --- .../manual/configuration/configuration.xml | 1 + nixos/doc/manual/default.nix | 1 + nixos/modules/services/editors/emacs.xml | 578 ++++++++++++++++++ 3 files changed, 580 insertions(+) create mode 100644 nixos/modules/services/editors/emacs.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 48810cc6ac6b..26f8ebad7344 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -31,6 +31,7 @@ effect after you run nixos-rebuild. + diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 1bec0d925222..2592766ee496 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -60,6 +60,7 @@ let cp ${../../modules/services/misc/taskserver/doc.xml} configuration/taskserver.xml cp ${../../modules/security/acme.xml} configuration/acme.xml cp ${../../modules/i18n/input-method/default.xml} configuration/input-methods.xml + cp ${../../modules/services/editors/emacs.xml} configuration/emacs.xml ln -s ${optionsDocBook} options-db.xml echo "${version}" > version ''; diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml new file mode 100644 index 000000000000..ee8ef512bc70 --- /dev/null +++ b/nixos/modules/services/editors/emacs.xml @@ -0,0 +1,578 @@ + + + Emacs + + + + + Emacs + is an extensible, customizable, self-documenting real-time display + editor — and more. At its core is an interpreter for Emacs Lisp, a + dialect of the Lisp programming language with extensions to + support text editing. + + + + Emacs runs within a graphical desktop environment using the X + Window System, but works equally well on a text terminal. Under + OS X, a "Mac port" edition is + available, which uses Apple's native GUI frameworks. + + + + Nixpkgs provides a superior environment + for running Emacs. It's simple to + create custom builds by overriding the default packages. Chaotic + collections of Emacs Lisp code and extensions can be brought under + control using declarative package + management. NixOS even provides a + systemd user service for automatically + starting the Emacs daemon. + + +
+ Installing <application>Emacs</application> + + + Emacs can installed in the normal way for Nix (see ). In addition, a NixOS + service can be enabled. + + +
+ The Different Releases of Emacs + + + Nixpkgs defines several basic Emacs + packages. The following are attributes belonging to the + pkgs set: + + + + emacs + emacs24 + + + The latest stable version of Emacs 24 using the GTK+ 2 widget + toolkit. + + + + + emacs24-nox + + + Emacs 24 built without any dependency on X11 + libraries. + + + + + emacs24Macport + + + Emacs 24 with the "Mac port" patches, providing a more + native look and feel under OS X. + + + + + emacs25pre + + + A pretest version of what will become the first + version of Emacs 25. + + + + + + + + If those aren't suitable, then the following imitation Emacs + editors are also available in Nixpkgs: + Zile, + mg, + Yi. + + +
+
+ Adding Packages to Emacs + + Emacs includes an entire ecosystem of functionality beyond + text editing, including a project planner, mail and news + reader, debugger interface, calendar, and more. + + + + Most extensions are gotten with the Emacs packaging system + (package.el) from Emacs Lisp Package Archive + (ELPA), + MELPA, + MELPA Stable, + and Org ELPA. + Nixpkgs is regularly updated to mirror all these archives. + + + + Under NixOS, you can continue to use + package-list-packages and + package-install to install packages. You + can also declare the set of Emacs packages you need using the + derivations from Nixpkgs. The rest of this section discusses + declarative installation of Emacs packages through nixpkgs. + + + + + This documentation describes the new Emacs packages + framework in NixOS 16.03 + (emacsPackagesNg) which should not be + confused with the previous and deprecated framework + (emacs24Packages). + + + + + The first step to declare the list of packages you want in + your Emacs installation is to create a dedicated + derivation. This can be done in a dedicated + emacs.nix file such as: + + + Nix expression to build Emacs with packages (<filename>emacs.nix</filename>) + +/* +This is a nix expression to build Emacs and some Emacs packages I like +from source on any distribution where Nix is installed. This will install +all the dependencies from the nixpkgs repository and build the binary files +without interfering with the host distribution. + +To build the project, type the following from the current directory: + +$ nix-build emacs.nix + +To run the newly compiled executable: + +$ ./result/bin/emacs +*/ +{ pkgs ? import <nixpkgs> {} }: + +let + myEmacs = pkgs.emacs; + emacsWithPackages = (pkgs.emacsPackagesNgGen myEmacs).emacsWithPackages; +in + emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ + magit # ; Integrate git <C-x g> + zerodark-theme # ; Nicolas' theme + ]) ++ (with epkgs.melpaPackages; [ + undo-tree # ; <C-x u> to show the undo tree + zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+> + ]) ++ (with epkgs.elpaPackages; [ + auctex # ; LaTeX mode + beacon # ; highlight my cursor when scrolling + nameless # ; hide current package name everywhere in elisp code + ]) ++ [ + pkgs.notmuch # From main packages set + ]) + + + + + + + The first non-comment line in this file + ({ pkgs ? ... }) + indicates that the whole file represents a function. + + + + + + The let expression below defines a + myEmacs binding pointing to the current + stable version of Emacs. This binding is here to separate the + choice of the Emacs binary from the specification of the + required packages. + + + + + + This generates an emacsWithPackages + function. It takes a single argument: a function from a + package set to a list of packages (the packages that will + be available in Emacs). + + + + + + The rest of the file specifies the list of packages to + install. In the example, two packages + (magit and + zerodark-theme) are taken from MELPA + stable. + + + + + + Two packages (undo-tree and + zoom-frm) are taken from MELPA. + + + + + Three packages are taken from GNU ELPA. + + + + + notmuch is taken from a nixpkgs derivation + which contains an Emacs mode. + + + + + + + + The result of this configuration will be an + emacs command which launches Emacs with all + of your chosen packages in the load-path. + + + + You can check that it works by executing this in a terminal: + + +$ nix-build emacs.nix +$ ./result/bin/emacs -q + + + and then typing M-x package-initialize. + Check that you can use all the packages you want in this + Emacs instance. For example, try switching to the zerodark + theme through + M-x load-theme <RET> zerodark <RET> y. + + + + + A few popular extensions worth checking out are: auctex, + company, edit-server, flycheck, helm, iedit, magit, + multiple-cursors, projectile, and yasnippet. + + + + + The list of available packages in the various ELPA + repositories can be seen with the following commands: + + Querying Emacs packages + " -qaP -A emacsPackagesNg.elpaPackages +nix-env -f "" -qaP -A emacsPackagesNg.melpaPackages +nix-env -f "" -qaP -A emacsPackagesNg.melpaStablePackages +nix-env -f "" -qaP -A emacsPackagesNg.orgPackages +]]> + + + + + If you are on NixOS, you can install this particular Emacs for + all users by adding it to the list of system packages + (see ). Simply + modify your file configuration.nix to + make it contain: + + Custom Emacs in <filename>configuration.nix</filename> + + + + + + In this case, the next nixos-rebuild switch + will take care of adding your emacs to the + PATH environment variable + (see ). + + + + + If you are not on NixOS or want to install this particular + Emacs only for yourself, you can do so by adding it to your + ~/.nixpkgs/config.nix + (see Nixpkgs manual): + + Custom Emacs in <filename>~/.nixpkgs/system.nix</filename> + + + + + + In this case, the next + nix-env -f '<nixpkgs>' -iA myemacs + will take care of adding your emacs to the + PATH environment variable. + +
+ +
+ Advanced Emacs Configuration + + + If you want, you can tweak the Emacs package itself from your + emacs.nix. For example, if you want to + have a GTK+3-based Emacs instead of the default GTK+2-based + binary and remove the automatically generated + emacs.desktop (useful is you only use + emacsclient), you can change your file + emacs.nix in this way: + + + + Custom Emacs build + {} }: +let + myEmacs = pkgs.lib.overrideDerivation (pkgs.emacs.override { + # Use gtk3 instead of the default gtk2 + withGTK3 = true; + withGTK2 = false; + }) (attrs: { + # I don't want emacs.desktop file because I only use + # emacsclient. + postInstall = attrs.postInstall + '' + rm $out/share/applications/emacs.desktop + ''; + }); +in [...] +]]> + + + + After building this file as shown in , + you will get an GTK3-based Emacs binary pre-loaded with your + favorite packages. + +
+
+ +
+ Running Emacs as a Service + + NixOS provides an optional + systemd service which launches + + Emacs daemon + + with the user's login session. + + + + Source: + modules/services/editors/emacs.nix + + +
+ Enabling the Service + + + To install and enable the systemd + user service for Emacs daemon, add the following to your + configuration.nix: + + + + + + The services.emacs.package option allows a + custom derivation to be used, for example, one created by + emacsWithPackages. + + + + Ensure that the Emacs server is enabled for your user's Emacs + configuration, either by customizing the + server-mode variable, or by adding + (server-start) to + ~/.emacs.d/init.el. + + + + To start the daemon, execute the following: + + +$ nixos-rebuild switch # to activate the new configuration.nix +$ systemctl --user daemon-reload # to force systemd reload +$ systemctl --user start emacs.service # to start the Emacs daemon + + + The server should now be ready to serve Emacs clients. + + +
+ +
+ Starting the client + + Ensure that the emacs server is enabled, either by customizing + the server-mode variable, or by adding + (server-start) to + ~/.emacs. + + + + To connect to the emacs daemon, run one of the following: + + +
+ +
+ Configuring the <varname>EDITOR</varname> variable + + + + If services.emacs.defaultEditor is + true, the EDITOR variable + will be set to a wrapper script which launches + emacsclient. + + + + Any setting of EDITOR in the shell config + files will override + services.emacs.defaultEditor. + To make sure EDITOR refers to the Emacs + wrapper script, remove any existing EDITOR + assignment from .profile, + .bashrc, .zshenv or + any other shell config file. + + + + If you have formed certain bad habits when editing files, + these can be corrected with a shell alias to the wrapper + script: + alias vi=$EDITOR + +
+ +
+ Per-User Enabling of the Service + + + In general, systemd user services + are globally enabled by symlinks in + /etc/systemd/user. In the case where + Emacs daemon is not wanted for all users, it is possible to + install the service but not globally enable it: + + + + + + To enable the systemd user service for just + the currently logged in user, run: + + systemctl --user enable emacs + + This will add the symlink + ~/.config/systemd/user/emacs.service. + +
+
+ +
+ Configuring Emacs + + + The Emacs init file should be changed to load the extension + packages at startup: + + + Package initialization in <filename>.emacs</filename> + + + + + + After the declarative emacs package configuration has been + tested, previously downloaded packages can be cleaned up by + removing ~/.emacs.d/elpa (do make a backup + first, in case you forgot a package). + + + + +
+ A Major Mode for Nix Expressions + + + Of interest may be melpaPackages.nix-mode, + which provides syntax highlighting for the Nix language. This is + particularly convenient if you regularly edit Nix files. + +
+ +
+ Accessing man pages + + You can use woman to get completion of all + available man pages. For example, type M-x woman + <RET> nixos-rebuild <RET>. + +
+
+ +