diff options
Diffstat (limited to 'nixos/modules/services/editors/emacs.xml')
| -rw-r--r-- | nixos/modules/services/editors/emacs.xml | 490 |
1 files changed, 0 insertions, 490 deletions
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml deleted file mode 100644 index 37d7a93a12b3..000000000000 --- a/nixos/modules/services/editors/emacs.xml +++ /dev/null @@ -1,490 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-emacs"> - <title>Emacs</title> - <para> - <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> - 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. - </para> - <para> - Emacs runs within a graphical desktop environment using the X Window - System, but works equally well on a text terminal. Under macOS, a - <quote>Mac port</quote> edition is available, which uses Apple’s - native GUI frameworks. - </para> - <para> - 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 <command>systemd</command> user service for automatically - starting the Emacs daemon. - </para> - <section xml:id="module-services-emacs-installing"> - <title>Installing Emacs</title> - <para> - Emacs can be installed in the normal way for Nix (see - <xref linkend="sec-package-management" />). In addition, a NixOS - <emphasis>service</emphasis> can be enabled. - </para> - <section xml:id="module-services-emacs-releases"> - <title>The Different Releases of Emacs</title> - <para> - Nixpkgs defines several basic Emacs packages. The following are - attributes belonging to the <varname>pkgs</varname> set: - </para> - <variablelist spacing="compact"> - <varlistentry> - <term> - <varname>emacs</varname> - </term> - <listitem> - <para> - The latest stable version of Emacs using the - <link xlink:href="http://www.gtk.org">GTK 2</link> widget - toolkit. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <varname>emacs-nox</varname> - </term> - <listitem> - <para> - Emacs built without any dependency on X11 libraries. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <varname>emacsMacport</varname> - </term> - <listitem> - <para> - Emacs with the <quote>Mac port</quote> patches, providing - a more native look and feel under macOS. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - If those aren’t suitable, then the following imitation Emacs - editors are also available in Nixpkgs: - <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, - <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, - <link xlink:href="http://yi-editor.github.io/">Yi</link>, - <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>. - </para> - </section> - <section xml:id="module-services-emacs-adding-packages"> - <title>Adding Packages to Emacs</title> - <para> - Emacs includes an entire ecosystem of functionality beyond text - editing, including a project planner, mail and news reader, - debugger interface, calendar, and more. - </para> - <para> - Most extensions are gotten with the Emacs packaging system - (<filename>package.el</filename>) from - <link xlink:href="https://elpa.gnu.org/">Emacs Lisp Package - Archive (ELPA)</link>, - <link xlink:href="https://melpa.org/">MELPA</link>, - <link xlink:href="https://stable.melpa.org/">MELPA - Stable</link>, and - <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. - Nixpkgs is regularly updated to mirror all these archives. - </para> - <para> - Under NixOS, you can continue to use - <literal>package-list-packages</literal> and - <literal>package-install</literal> 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. - </para> - <para> - 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 <filename>emacs.nix</filename> file such - as: - </para> - <para> - <anchor xml:id="ex-emacsNix" /> - </para> - <programlisting language="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 -*/ - -# The first non-comment line in this file indicates that -# the whole file represents a function. -{ pkgs ? import <nixpkgs> {} }: - -let - # 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. - myEmacs = pkgs.emacs; - # 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). - emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages; -in - # 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. - emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ - magit # ; Integrate git <C-x g> - zerodark-theme # ; Nicolas' theme - ]) - # Two packages (undo-tree and zoom-frm) are taken from MELPA. - ++ (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-+> - ]) - # Three packages are taken from GNU ELPA. - ++ (with epkgs.elpaPackages; [ - auctex # ; LaTeX mode - beacon # ; highlight my cursor when scrolling - nameless # ; hide current package name everywhere in elisp code - ]) - # notmuch is taken from a nixpkgs derivation which contains an Emacs mode. - ++ [ - pkgs.notmuch # From main packages set - ]) -</programlisting> - <para> - The result of this configuration will be an - <command>emacs</command> command which launches Emacs with all - of your chosen packages in the <varname>load-path</varname>. - </para> - <para> - You can check that it works by executing this in a terminal: - </para> - <programlisting> -$ nix-build emacs.nix -$ ./result/bin/emacs -q -</programlisting> - <para> - and then typing <literal>M-x package-initialize</literal>. Check - that you can use all the packages you want in this Emacs - instance. For example, try switching to the zerodark theme - through - <literal>M-x load-theme <RET> zerodark <RET> y</literal>. - </para> - <tip> - <para> - A few popular extensions worth checking out are: auctex, - company, edit-server, flycheck, helm, iedit, magit, - multiple-cursors, projectile, and yasnippet. - </para> - </tip> - <para> - The list of available packages in the various ELPA repositories - can be seen with the following commands: - <anchor xml:id="module-services-emacs-querying-packages" /> - </para> - <programlisting> -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages -</programlisting> - <para> - If you are on NixOS, you can install this particular Emacs for - all users by adding it to the list of system packages (see - <xref linkend="sec-declarative-package-mgmt" />). Simply modify - your file <filename>configuration.nix</filename> to make it - contain: - <anchor xml:id="module-services-emacs-configuration-nix" /> - </para> - <programlisting> -{ - environment.systemPackages = [ - # [...] - (import /path/to/emacs.nix { inherit pkgs; }) - ]; -} -</programlisting> - <para> - In this case, the next <command>nixos-rebuild switch</command> - will take care of adding your <command>emacs</command> to the - <varname>PATH</varname> environment variable (see - <xref linkend="sec-changing-config" />). - </para> - <para> - 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 - <filename>~/.config/nixpkgs/config.nix</filename> (see - <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs - manual</link>): - <anchor xml:id="module-services-emacs-config-nix" /> - </para> - <programlisting> -{ - packageOverrides = super: let self = super.pkgs; in { - myemacs = import /path/to/emacs.nix { pkgs = self; }; - }; -} -</programlisting> - <para> - In this case, the next - <literal>nix-env -f '<nixpkgs>' -iA myemacs</literal> will - take care of adding your emacs to the <varname>PATH</varname> - environment variable. - </para> - </section> - <section xml:id="module-services-emacs-advanced"> - <title>Advanced Emacs Configuration</title> - <para> - If you want, you can tweak the Emacs package itself from your - <filename>emacs.nix</filename>. 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 - <filename>emacs.desktop</filename> (useful if you only use - <command>emacsclient</command>), you can change your file - <filename>emacs.nix</filename> in this way: - </para> - <para> - <anchor xml:id="ex-emacsGtk3Nix" /> - </para> - <programlisting> -{ pkgs ? import <nixpkgs> {} }: -let - myEmacs = (pkgs.emacs.override { - # Use gtk3 instead of the default gtk2 - withGTK3 = true; - withGTK2 = false; - }).overrideAttrs (attrs: { - # I don't want emacs.desktop file because I only use - # emacsclient. - postInstall = (attrs.postInstall or "") + '' - rm $out/share/applications/emacs.desktop - ''; - }); -in [...] -</programlisting> - <para> - After building this file as shown in - <link linkend="ex-emacsNix">the example above</link>, you will - get an GTK 3-based Emacs binary pre-loaded with your favorite - packages. - </para> - </section> - </section> - <section xml:id="module-services-emacs-running"> - <title>Running Emacs as a Service</title> - <para> - NixOS provides an optional <command>systemd</command> service - which launches - <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">Emacs - daemon</link> with the user’s login session. - </para> - <para> - <emphasis>Source:</emphasis> - <filename>modules/services/editors/emacs.nix</filename> - </para> - <section xml:id="module-services-emacs-enabling"> - <title>Enabling the Service</title> - <para> - To install and enable the <command>systemd</command> user - service for Emacs daemon, add the following to your - <filename>configuration.nix</filename>: - </para> - <programlisting> -services.emacs.enable = true; -services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; }; -</programlisting> - <para> - The <varname>services.emacs.package</varname> option allows a - custom derivation to be used, for example, one created by - <literal>emacsWithPackages</literal>. - </para> - <para> - Ensure that the Emacs server is enabled for your user’s Emacs - configuration, either by customizing the - <varname>server-mode</varname> variable, or by adding - <literal>(server-start)</literal> to - <filename>~/.emacs.d/init.el</filename>. - </para> - <para> - To start the daemon, execute the following: - </para> - <programlisting> -$ 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 -</programlisting> - <para> - The server should now be ready to serve Emacs clients. - </para> - </section> - <section xml:id="module-services-emacs-starting-client"> - <title>Starting the client</title> - <para> - Ensure that the emacs server is enabled, either by customizing - the <varname>server-mode</varname> variable, or by adding - <literal>(server-start)</literal> to - <filename>~/.emacs</filename>. - </para> - <para> - To connect to the emacs daemon, run one of the following: - </para> - <programlisting> -emacsclient FILENAME -emacsclient --create-frame # opens a new frame (window) -emacsclient --create-frame --tty # opens a new frame on the current terminal -</programlisting> - </section> - <section xml:id="module-services-emacs-editor-variable"> - <title>Configuring the <varname>EDITOR</varname> variable</title> - <para> - If <xref linkend="opt-services.emacs.defaultEditor" /> is - <literal>true</literal>, the <varname>EDITOR</varname> variable - will be set to a wrapper script which launches - <command>emacsclient</command>. - </para> - <para> - Any setting of <varname>EDITOR</varname> in the shell config - files will override - <varname>services.emacs.defaultEditor</varname>. To make sure - <varname>EDITOR</varname> refers to the Emacs wrapper script, - remove any existing <varname>EDITOR</varname> assignment from - <filename>.profile</filename>, <filename>.bashrc</filename>, - <filename>.zshenv</filename> or any other shell config file. - </para> - <para> - If you have formed certain bad habits when editing files, these - can be corrected with a shell alias to the wrapper script: - </para> - <programlisting> -alias vi=$EDITOR -</programlisting> - </section> - <section xml:id="module-services-emacs-per-user"> - <title>Per-User Enabling of the Service</title> - <para> - In general, <command>systemd</command> user services are - globally enabled by symlinks in - <filename>/etc/systemd/user</filename>. In the case where Emacs - daemon is not wanted for all users, it is possible to install - the service but not globally enable it: - </para> - <programlisting> -services.emacs.enable = false; -services.emacs.install = true; -</programlisting> - <para> - To enable the <command>systemd</command> user service for just - the currently logged in user, run: - </para> - <programlisting> -systemctl --user enable emacs -</programlisting> - <para> - This will add the symlink - <filename>~/.config/systemd/user/emacs.service</filename>. - </para> - </section> - </section> - <section xml:id="module-services-emacs-configuring"> - <title>Configuring Emacs</title> - <para> - The Emacs init file should be changed to load the extension - packages at startup: - <anchor xml:id="module-services-emacs-package-initialisation" /> - </para> - <programlisting> -(require 'package) - -;; optional. makes unpure packages archives unavailable -(setq package-archives nil) - -(setq package-enable-at-startup nil) -(package-initialize) -</programlisting> - <para> - After the declarative emacs package configuration has been tested, - previously downloaded packages can be cleaned up by removing - <filename>~/.emacs.d/elpa</filename> (do make a backup first, in - case you forgot a package). - </para> - <section xml:id="module-services-emacs-major-mode"> - <title>A Major Mode for Nix Expressions</title> - <para> - Of interest may be <varname>melpaPackages.nix-mode</varname>, - which provides syntax highlighting for the Nix language. This is - particularly convenient if you regularly edit Nix files. - </para> - </section> - <section xml:id="module-services-emacs-man-pages"> - <title>Accessing man pages</title> - <para> - You can use <literal>woman</literal> to get completion of all - available man pages. For example, type - <literal>M-x woman <RET> nixos-rebuild <RET>.</literal> - </para> - </section> - <section xml:id="sec-emacs-docbook-xml"> - <title>Editing DocBook 5 XML Documents</title> - <para> - Emacs includes - <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, - a major-mode for validating and editing XML documents. When - editing DocBook 5.0 documents, such as - <link linkend="book-nixos-manual">this one</link>, nXML needs to - be configured with the relevant schema, which is not included. - </para> - <para> - To install the DocBook 5.0 schemas, either add - <varname>pkgs.docbook5</varname> to - <xref linkend="opt-environment.systemPackages" /> - (<link linkend="sec-declarative-package-mgmt">NixOS</link>), or - run <literal>nix-env -f '<nixpkgs>' -iA docbook5</literal> - (<link linkend="sec-ad-hoc-packages">Nix</link>). - </para> - <para> - Then customize the variable - <varname>rng-schema-locating-files</varname> to include - <filename>~/.emacs.d/schemas.xml</filename> and put the - following text into that file: - <anchor xml:id="ex-emacs-docbook-xml" /> - </para> - <programlisting language="xml"> -<?xml version="1.0"?> -<!-- - To let emacs find this file, evaluate: - (add-to-list 'rng-schema-locating-files "~/.emacs.d/schemas.xml") ---> -<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"> - <!-- - Use this variation if pkgs.docbook5 is added to environment.systemPackages - --> - <namespace ns="http://docbook.org/ns/docbook" - uri="/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc"/> - <!-- - Use this variation if installing schema with "nix-env -iA pkgs.docbook5". - <namespace ns="http://docbook.org/ns/docbook" - uri="../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc"/> - --> -</locatingRules> -</programlisting> - </section> - </section> -</chapter> |