diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 48810cc6ac6..26f8ebad734 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 1bec0d92522..2592766ee49 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 00000000000..ee8ef512bc7
--- /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 Emacs
+
+
+ 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 (emacs.nix)
+
+/*
+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 configuration.nix
+
+
+
+
+
+ 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 ~/.nixpkgs/system.nix
+
+
+
+
+
+ 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 EDITOR 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 .emacs
+
+
+
+
+
+ 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>.
+
+
+
+
+