docs: format
This commit is contained in:
Graham Christensen
@@ -3,150 +3,148 @@
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="module-services-emacs">
|
||||
|
||||
<title>Emacs</title>
|
||||
|
||||
<!--
|
||||
<title>Emacs</title>
|
||||
<!--
|
||||
Documentation contributors:
|
||||
Damien Cassou @DamienCassou
|
||||
Thomas Tuegel @ttuegel
|
||||
Rodney Lorrimar @rvl
|
||||
-->
|
||||
<para>
|
||||
<link xlink:href="http://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
|
||||
<productname>macOS</productname>, a "Mac port" edition is available, which
|
||||
uses Apple's native GUI frameworks.
|
||||
</para>
|
||||
<para>
|
||||
<productname>Nixpkgs</productname> provides a superior environment for
|
||||
running <application>Emacs</application>. 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. <productname>NixOS</productname> even provides a
|
||||
<command>systemd</command> user service for automatically starting the Emacs
|
||||
daemon.
|
||||
</para>
|
||||
<section xml:id="module-services-emacs-installing">
|
||||
<title>Installing <application>Emacs</application></title>
|
||||
|
||||
<para>
|
||||
<link xlink:href="http://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.
|
||||
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>
|
||||
|
||||
<para>
|
||||
Emacs runs within a graphical desktop environment using the X
|
||||
Window System, but works equally well on a text terminal. Under
|
||||
<productname>macOS</productname>, a "Mac port" edition is
|
||||
available, which uses Apple's native GUI frameworks.
|
||||
</para>
|
||||
<section xml:id="module-services-emacs-releases">
|
||||
<title>The Different Releases of Emacs</title>
|
||||
|
||||
<para>
|
||||
<productname>Nixpkgs</productname> provides a superior environment
|
||||
for running <application>Emacs</application>. 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. <productname>NixOS</productname> even provides a
|
||||
<command>systemd</command> user service for automatically
|
||||
starting the Emacs daemon.
|
||||
</para>
|
||||
<para>
|
||||
<productname>Nixpkgs</productname> defines several basic Emacs packages.
|
||||
The following are attributes belonging to the <varname>pkgs</varname> set:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>emacs</varname>
|
||||
</term>
|
||||
<term>
|
||||
<varname>emacs25</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The latest stable version of Emacs 25 using the
|
||||
<link
|
||||
xlink:href="http://www.gtk.org">GTK+ 2</link>
|
||||
widget toolkit.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>emacs25-nox</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Emacs 25 built without any dependency on X11 libraries.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>emacsMacport</varname>
|
||||
</term>
|
||||
<term>
|
||||
<varname>emacs25Macport</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Emacs 25 with the "Mac port" patches, providing a more native look and
|
||||
feel under macOS.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<section xml:id="module-services-emacs-installing">
|
||||
<title>Installing <application>Emacs</application></title>
|
||||
<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>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<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-adding-packages">
|
||||
<title>Adding Packages to Emacs</title>
|
||||
|
||||
<section xml:id="module-services-emacs-releases">
|
||||
<title>The Different Releases of 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>
|
||||
<productname>Nixpkgs</productname> defines several basic Emacs
|
||||
packages. The following are attributes belonging to the
|
||||
<varname>pkgs</varname> set:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><varname>emacs</varname></term>
|
||||
<term><varname>emacs25</varname></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The latest stable version of Emacs 25 using the <link
|
||||
xlink:href="http://www.gtk.org">GTK+ 2</link> widget
|
||||
toolkit.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><varname>emacs25-nox</varname></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Emacs 25 built without any dependency on X11
|
||||
libraries.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><varname>emacsMacport</varname></term>
|
||||
<term><varname>emacs25Macport</varname></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Emacs 25 with the "Mac port" patches, providing a more
|
||||
native look and feel under macOS.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<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>.
|
||||
</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
|
||||
<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
|
||||
(<acronym>ELPA</acronym>)</link>,
|
||||
<link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></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>
|
||||
(<acronym>ELPA</acronym>)</link>,
|
||||
<link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></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
|
||||
<function>package-list-packages</function> and
|
||||
<function>package-install</function> 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>
|
||||
Under NixOS, you can continue to use
|
||||
<function>package-list-packages</function> and
|
||||
<function>package-install</function> 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>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This documentation describes the new Emacs packages
|
||||
framework in NixOS 16.03
|
||||
(<varname>emacsPackagesNg</varname>) which should not be
|
||||
confused with the previous and deprecated framework
|
||||
(<varname>emacs24Packages</varname>).
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>
|
||||
This documentation describes the new Emacs packages framework in NixOS
|
||||
16.03 (<varname>emacsPackagesNg</varname>) which should not be confused
|
||||
with the previous and deprecated framework
|
||||
(<varname>emacs24Packages</varname>).
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<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:
|
||||
|
||||
<example xml:id="ex-emacsNix">
|
||||
<title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
|
||||
<programlisting language="nix">
|
||||
<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:
|
||||
<example xml:id="ex-emacsNix">
|
||||
<title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
|
||||
<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
|
||||
@@ -181,119 +179,104 @@ in
|
||||
pkgs.notmuch # From main packages set <co xml:id="ex-emacsNix-7" />
|
||||
])
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
<calloutlist>
|
||||
<callout arearefs="ex-emacsNix-1">
|
||||
<para>
|
||||
The first non-comment line in this file
|
||||
(<literal>{ pkgs ? ... }</literal>)
|
||||
indicates that the whole file represents a function.
|
||||
</para>
|
||||
</callout>
|
||||
|
||||
<callout arearefs="ex-emacsNix-2">
|
||||
<para>
|
||||
The <varname>let</varname> expression below defines a
|
||||
<varname>myEmacs</varname> 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.
|
||||
</para>
|
||||
</callout>
|
||||
|
||||
<callout arearefs="ex-emacsNix-3">
|
||||
<para>
|
||||
This generates an <varname>emacsWithPackages</varname>
|
||||
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).
|
||||
</para>
|
||||
</callout>
|
||||
|
||||
<callout arearefs="ex-emacsNix-4">
|
||||
<para>
|
||||
The rest of the file specifies the list of packages to
|
||||
install. In the example, two packages
|
||||
(<varname>magit</varname> and
|
||||
<varname>zerodark-theme</varname>) are taken from MELPA
|
||||
stable.
|
||||
</para>
|
||||
</callout>
|
||||
|
||||
<callout arearefs="ex-emacsNix-5">
|
||||
<para>
|
||||
Two packages (<varname>undo-tree</varname> and
|
||||
<varname>zoom-frm</varname>) are taken from MELPA.
|
||||
</para>
|
||||
</callout>
|
||||
|
||||
<callout arearefs="ex-emacsNix-6">
|
||||
<para>Three packages are taken from GNU ELPA.</para>
|
||||
</callout>
|
||||
|
||||
<callout arearefs="ex-emacsNix-7">
|
||||
<para>
|
||||
<varname>notmuch</varname> is taken from a nixpkgs derivation
|
||||
which contains an Emacs mode.
|
||||
</para>
|
||||
</callout>
|
||||
|
||||
</calloutlist>
|
||||
</para>
|
||||
|
||||
</example>
|
||||
<calloutlist>
|
||||
<callout arearefs="ex-emacsNix-1">
|
||||
<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>.
|
||||
The first non-comment line in this file (<literal>{ pkgs ? ...
|
||||
}</literal>) indicates that the whole file represents a function.
|
||||
</para>
|
||||
|
||||
</callout>
|
||||
<callout arearefs="ex-emacsNix-2">
|
||||
<para>
|
||||
You can check that it works by executing this in a terminal:
|
||||
The <varname>let</varname> expression below defines a
|
||||
<varname>myEmacs</varname> 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.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-emacsNix-3">
|
||||
<para>
|
||||
This generates an <varname>emacsWithPackages</varname> 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).
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-emacsNix-4">
|
||||
<para>
|
||||
The rest of the file specifies the list of packages to install. In the
|
||||
example, two packages (<varname>magit</varname> and
|
||||
<varname>zerodark-theme</varname>) are taken from MELPA stable.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-emacsNix-5">
|
||||
<para>
|
||||
Two packages (<varname>undo-tree</varname> and
|
||||
<varname>zoom-frm</varname>) are taken from MELPA.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-emacsNix-6">
|
||||
<para>
|
||||
Three packages are taken from GNU ELPA.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-emacsNix-7">
|
||||
<para>
|
||||
<varname>notmuch</varname> is taken from a nixpkgs derivation which
|
||||
contains an Emacs mode.
|
||||
</para>
|
||||
</callout>
|
||||
</calloutlist>
|
||||
</para>
|
||||
|
||||
<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:
|
||||
<screen>
|
||||
$ nix-build emacs.nix
|
||||
$ ./result/bin/emacs -q
|
||||
</screen>
|
||||
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>
|
||||
|
||||
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>
|
||||
|
||||
<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:
|
||||
<example xml:id="module-services-emacs-querying-packages">
|
||||
<title>Querying Emacs packages</title>
|
||||
<programlisting><![CDATA[
|
||||
<para>
|
||||
The list of available packages in the various ELPA repositories can be seen
|
||||
with the following commands:
|
||||
<example xml:id="module-services-emacs-querying-packages">
|
||||
<title>Querying Emacs packages</title>
|
||||
<programlisting><![CDATA[
|
||||
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.elpaPackages
|
||||
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaPackages
|
||||
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaStablePackages
|
||||
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<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:
|
||||
<example xml:id="module-services-emacs-configuration-nix">
|
||||
<title>Custom Emacs in <filename>configuration.nix</filename></title>
|
||||
<programlisting><![CDATA[
|
||||
<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:
|
||||
<example xml:id="module-services-emacs-configuration-nix">
|
||||
<title>Custom Emacs in <filename>configuration.nix</filename></title>
|
||||
<programlisting><![CDATA[
|
||||
{
|
||||
environment.systemPackages = [
|
||||
# [...]
|
||||
@@ -301,60 +284,59 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
|
||||
];
|
||||
}
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<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>
|
||||
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>
|
||||
|
||||
<!-- fixme: i think the following is better done with config.nix
|
||||
https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
|
||||
-->
|
||||
<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="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>):
|
||||
<example xml:id="module-services-emacs-config-nix">
|
||||
<title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>
|
||||
<programlisting><![CDATA[
|
||||
|
||||
<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="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs
|
||||
manual</link>):
|
||||
<example xml:id="module-services-emacs-config-nix">
|
||||
<title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>
|
||||
<programlisting><![CDATA[
|
||||
{
|
||||
packageOverrides = super: let self = super.pkgs; in {
|
||||
myemacs = import /path/to/emacs.nix { pkgs = self; };
|
||||
};
|
||||
}
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
<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 is you only use
|
||||
<command>emacsclient</command>), you can change your file
|
||||
<filename>emacs.nix</filename> in this way:
|
||||
</para>
|
||||
<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 is you
|
||||
only use <command>emacsclient</command>), you can change your file
|
||||
<filename>emacs.nix</filename> in this way:
|
||||
</para>
|
||||
|
||||
<example xml:id="ex-emacsGtk3Nix">
|
||||
<title>Custom Emacs build</title>
|
||||
<programlisting><![CDATA[
|
||||
<example xml:id="ex-emacsGtk3Nix">
|
||||
<title>Custom Emacs build</title>
|
||||
<programlisting><![CDATA[
|
||||
{ pkgs ? import <nixpkgs> {} }:
|
||||
let
|
||||
myEmacs = (pkgs.emacs.override {
|
||||
@@ -370,161 +352,143 @@ let
|
||||
});
|
||||
in [...]
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</example>
|
||||
|
||||
<para>
|
||||
After building this file as shown in <xref linkend="ex-emacsNix" />,
|
||||
you will get an GTK3-based Emacs binary pre-loaded with your
|
||||
favorite packages.
|
||||
</para>
|
||||
</section>
|
||||
<para>
|
||||
After building this file as shown in <xref linkend="ex-emacsNix" />, you
|
||||
will get an GTK3-based Emacs binary pre-loaded with your favorite packages.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-emacs-running">
|
||||
</section>
|
||||
<section xml:id="module-services-emacs-running">
|
||||
<title>Running Emacs as a Service</title>
|
||||
|
||||
<para>
|
||||
<productname>NixOS</productname> 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.
|
||||
<productname>NixOS</productname> 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>
|
||||
<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>:
|
||||
<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>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.emacs.enable"/> = true;
|
||||
<xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; };
|
||||
</programlisting>
|
||||
</para>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <varname>services.emacs.package</varname> option allows a
|
||||
custom derivation to be used, for example, one created by
|
||||
<function>emacsWithPackages</function>.
|
||||
</para>
|
||||
<para>
|
||||
The <varname>services.emacs.package</varname> option allows a custom
|
||||
derivation to be used, for example, one created by
|
||||
<function>emacsWithPackages</function>.
|
||||
</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>
|
||||
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:
|
||||
<screen>
|
||||
$ 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
|
||||
</screen>
|
||||
|
||||
The server should now be ready to serve Emacs clients.
|
||||
</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>
|
||||
<title>Starting the client</title>
|
||||
|
||||
<para>
|
||||
To connect to the emacs daemon, run one of the following:
|
||||
<programlisting><![CDATA[
|
||||
<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:
|
||||
<programlisting><![CDATA[
|
||||
emacsclient FILENAME
|
||||
emacsclient --create-frame # opens a new frame (window)
|
||||
emacsclient --create-frame --tty # opens a new frame on the current terminal
|
||||
]]></programlisting>
|
||||
</para>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-emacs-editor-variable">
|
||||
<title>Configuring the <varname>EDITOR</varname> variable</title>
|
||||
<!--<title><command>emacsclient</command> as the Default Editor</title>-->
|
||||
<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>
|
||||
<!--<title><command>emacsclient</command> as the Default Editor</title>-->
|
||||
|
||||
<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 <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>
|
||||
If you have formed certain bad habits when editing files,
|
||||
these can be corrected with a shell alias to the wrapper
|
||||
script:
|
||||
<programlisting>alias vi=$EDITOR</programlisting>
|
||||
</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:
|
||||
<programlisting>alias vi=$EDITOR</programlisting>
|
||||
</para>
|
||||
</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:
|
||||
<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:
|
||||
<programlisting>
|
||||
<xref linkend="opt-services.emacs.enable"/> = false;
|
||||
<xref linkend="opt-services.emacs.install"/> = true;
|
||||
</programlisting>
|
||||
</para>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To enable the <command>systemd</command> user service for just
|
||||
the currently logged in user, run:
|
||||
|
||||
<programlisting>systemctl --user enable emacs</programlisting>
|
||||
|
||||
This will add the symlink
|
||||
<filename>~/.config/systemd/user/emacs.service</filename>.
|
||||
</para>
|
||||
<para>
|
||||
To enable the <command>systemd</command> user service for just the
|
||||
currently logged in user, run:
|
||||
<programlisting>systemctl --user enable emacs</programlisting>
|
||||
This will add the symlink
|
||||
<filename>~/.config/systemd/user/emacs.service</filename>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-emacs-configuring">
|
||||
</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:
|
||||
|
||||
<example xml:id="module-services-emacs-package-initialisation">
|
||||
<title>Package initialization in <filename>.emacs</filename></title>
|
||||
<programlisting><![CDATA[
|
||||
The Emacs init file should be changed to load the extension packages at
|
||||
startup:
|
||||
<example xml:id="module-services-emacs-package-initialisation">
|
||||
<title>Package initialization in <filename>.emacs</filename></title>
|
||||
<programlisting><![CDATA[
|
||||
(require 'package)
|
||||
|
||||
;; optional. makes unpure packages archives unavailable
|
||||
@@ -533,66 +497,71 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
|
||||
(setq package-enable-at-startup nil)
|
||||
(package-initialize)
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<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).
|
||||
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>
|
||||
|
||||
<!--
|
||||
<!--
|
||||
todo: is it worth documenting customizations for
|
||||
server-switch-hook, server-done-hook?
|
||||
-->
|
||||
|
||||
<section xml:id="module-services-emacs-major-mode">
|
||||
<title>A Major Mode for Nix Expressions</title>
|
||||
<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>
|
||||
<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 <function>woman</function> to get completion of all
|
||||
available man pages. For example, type <literal>M-x woman
|
||||
<RET> nixos-rebuild <RET>.</literal>
|
||||
</para>
|
||||
<title>Accessing man pages</title>
|
||||
|
||||
<para>
|
||||
You can use <function>woman</function> 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
|
||||
<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>
|
||||
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
|
||||
<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 -i pkgs.docbook5</literal>
|
||||
(<link linkend="sec-ad-hoc-packages">Nix</link>).
|
||||
</para>
|
||||
<literal>nix-env -i pkgs.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:
|
||||
<example xml:id="ex-emacs-docbook-xml">
|
||||
<title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
|
||||
<programlisting language="xml"><![CDATA[
|
||||
<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:
|
||||
<example xml:id="ex-emacs-docbook-xml">
|
||||
<title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
|
||||
<programlisting language="xml"><![CDATA[
|
||||
<?xml version="1.0"?>
|
||||
<!--
|
||||
To let emacs find this file, evaluate:
|
||||
@@ -612,9 +581,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
|
||||
</locatingRules>
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
Reference in New Issue
Block a user