Official NixOS Wiki

Emacs: Difference between revisions

← Older editNewer edit →
Layer-09 (talk | contribs)
175 edits
VisualWikitext
Change formatting and wording to match the manual of style guidelines
Layer-09 (talk | contribs)
175 edits
Revamped the page
Line 1: Line 1:
[https://www.gnu.org/software/emacs/ Emacs] is a versatile and powerful software application, valued for its exceptional extensibility, allowing users to tailor the editor to their specific needs. It boasts an automatic self-documenting behavior, providing users with readily accessible information about functions, variables, and keybindings. The flexibility of Emacs enables it to adapt to various workflows and programming styles, while its syntax awareness enhances coding efficiency across multiple languages. Its extensive package repository surpasses many of its competitors, including [[Vim]] and its fork [[Neovim]], making it one of the most customizable and feature-rich editors available.  
{{User:Layer-09/Sandbox/Infobox Emacs
| title                  = GNU Emacs
| image                  = EmacsIcon.svg
| paradigm                = Functional, meta, reflective
| family                  = Lisp
| designed_by            = [[Richard Stallman]], [[Guy L. Steele, Jr.]]
| developer              = [[GNU Project]]
| first_appeared          = 1985; 40 years ago
| stable_release          = 29.4 / 22 June 2024; 11 months ago
| os                      = Cross-platform
| license                = [[GNU General Public License]]
| filename_extensions    = .el, .elc, .eln
| website                = [https://www.gnu.org/software/emacs gnu.org/emacs]
}}[https://www.gnu.org/software/emacs/ Emacs] is a free and open-source text editor known for its exceptional extensibility and adaptability. It can be customized into anything from a simple editor to a full development environment or productivity tool. Emacs features built-in self-documentation, syntax-aware editing, and a vast ecosystem of community-developed packages.<ref>https://www.gnu.org/software/emacs/</ref>


For those seeking a more approachable entry point to the Emacs ecosystem, the [https://doomemacs.org Doom Emacs] project offers a framework with a beginner-friendly default configuration. Doom Emacs comes pre-configured with popular modules for features such as IDE-like functionality, note-taking, and time management.
For an easier introduction, [https://doomemacs.org Doom Emacs] offers a pre-configured Emacs framework with modern defaults and features like IDE tools, note-taking, and task management.<ref>https://doomemacs.org</ref>


There is an official Matrix room for Nix/Emacs: [https://matrix.to/#/#emacs:nixos.org #emacs:nixos.org].
There is an official Matrix room for Nix/Emacs: [https://matrix.to/#/#emacs:nixos.org #emacs:nixos.org].
Line 7: Line 20:
== Installation ==
== Installation ==


==== Using nix-shell ====
==== Shell ====
<syntaxhighlight lang="console" start="3">
 
$ nix-shell -p emacs
To temporarily use Emacs in a shell environment without modifying your system configuration, you can run:
<syntaxhighlight lang="bash">
nix-shell -p emacs
</syntaxhighlight>
</syntaxhighlight>
This makes the Emacs editor available in your current shell. You can then launch Emacs by typing `emacs`.
==== System setup ====


==== Using Global Configuration ====
To install Emacs system-wide, making it available to all users, add the following to your <code>/etc/nixos/configuration.nix</code>:
<syntaxhighlight lang="text">
<syntaxhighlight lang="nix">
# Example for /etc/nixos/configuration.nix
environment.systemPackages = [
environment.systemPackages = [
  pkgs.emacs
  pkgs.emacs
];
];
</syntaxhighlight>Apply these changes by running:<syntaxhighlight lang="console">
# nixos-rebuild switch
</syntaxhighlight>


==== Using Home Configuration ====
# User-specific installation (in ~/.config/nixpkgs/home.nix)
<syntaxhighlight lang="text">
home.packages = [
home.packages = [  
   pkgs.emacs
   pkgs.emacs  
];
];
</syntaxhighlight>Apply the changes by running:<syntaxhighlight lang="console">
$ home-manager switch
</syntaxhighlight>
</syntaxhighlight>
After rebuilding your system with <code>nixos-rebuild switch</code> or <code>home-manager switch</code>, Emacs will be installed and accessible.


== Configuration ==
== Configuration ==
Line 62: Line 76:


== Tips and Tricks ==
== Tips and Tricks ==
==== Location of Options ====
The home manager options are defined in the following [https://nix-community.github.io/home-manager/options.xhtml#opt-programs.emacs.enable Home Manager Options Manual].
The global options are listed here [https://search.nixos.org/options?channel=unstable&query=services.emacs services.emacs.*].


==== Installing Packages ====
==== Installing Packages ====
{{tip|Emacs, much like NixOS can rebuild and re-fetch all of its packages based on its initialization file alone, if one chooses to use an extension called {{ic|(use-package)}}. Such a configuration file can be version controlled and used in all compatible operating systems.}}  
{{Note|Emacs, much like NixOS can rebuild and re-fetch all of its packages based on its initialization file alone, if one chooses to use an extension called "use-package". Such a configuration file can be version controlled and used in all compatible operating systems.}}
One can mix and match whether Emacs packages are installed by Nix or Emacs. This can be particularly useful for Emacs packages that need to be built, such as vterm. One way to install Emacs packages through Nix is by the following, replacing {{ic|emacsPgtkNativeComp}} with the variant in use:<syntaxhighlight lang="nix">
One can mix and match whether Emacs packages are installed by Nix or Emacs. This can be particularly useful for Emacs packages that need to be built, such as vterm. One way to install Emacs packages through Nix is by the following, replacing {{ic|emacsPgtkNativeComp}} with the variant in use:<syntaxhighlight lang="nix">
environment.systemPackages = with pkgs;
environment.systemPackages = with pkgs;
Line 258: Line 267:
{{warning| Certain issues are possible, when mixing different versions of Emacs, in particular a configuration file tailored towards emacs with native compilation, may misbehave on non-native compiling versions, unless only the emacs lisp code is shared between them.}}
{{warning| Certain issues are possible, when mixing different versions of Emacs, in particular a configuration file tailored towards emacs with native compilation, may misbehave on non-native compiling versions, unless only the emacs lisp code is shared between them.}}


===== 1. Stable (nixpkgs) =====
===== Stable (nixpkgs) =====
Emacs is available in nixpkgs under the names <code>emacs</code> and <code>emacs-gtk</code>.
Emacs is available in nixpkgs under the names <code>emacs</code> and <code>emacs-gtk</code>.


[https://github.com/NixOS/nixpkgs/pull/189543 Since 2022-09], the package called <code>emacs</code> now installs the lucid toolkit instead of gtk. The reason is that Emacs is less stable with gtk especially in daemon mode. However, the lucid flavor of Emacs will not take into account the GTK theme (since it is not even GTK) and looks quite… ugly (see comparisons [https://emacs.stackexchange.com/questions/33065/on-linux-why-should-one-choose-lucid-over-gtk-gui-for-emacs here]). If you still prefer the GTK version of Emacs, you can instead install <code>emacs-gtk</code> (before 2022-09 this package does not exist and Emacs defaults to the gtk version).
[https://github.com/NixOS/nixpkgs/pull/189543 Since 2022-09], the package called <code>emacs</code> now installs the lucid toolkit instead of gtk. The reason is that Emacs is less stable with gtk especially in daemon mode. However, the lucid flavor of Emacs will not take into account the GTK theme (since it is not even GTK) and looks quite… ugly (see comparisons [https://emacs.stackexchange.com/questions/33065/on-linux-why-should-one-choose-lucid-over-gtk-gui-for-emacs here]). If you still prefer the GTK version of Emacs, you can instead install <code>emacs-gtk</code> (before 2022-09 this package does not exist and Emacs defaults to the gtk version).


===== 2. Unstable (community overlay) =====
===== Unstable (community overlay) =====
The [https://github.com/nix-community/emacs-overlay community overlay] provides nightly versions of the Emacs unstable branches, ELPA/MELPA packages, and [https://github.com/ch11ng/exwm EXWM] + its dependencies. '''To use these, first apply the overlay (instructions below), which will make the packages available in nixpkgs.''' Then you can follow the normal nixpkgs installation instructions (above), but use your package of choice from the overlay (e.g. <code>pkgs.emacsGit</code>) in place of <code>pkgs.emacs</code>. See the [https://github.com/nix-community/emacs-overlay#emacs-overlay README] for a complete list of packages provided, and their differences.
The [https://github.com/nix-community/emacs-overlay community overlay] provides nightly versions of the Emacs unstable branches, ELPA/MELPA packages, and [https://github.com/ch11ng/exwm EXWM] + its dependencies. '''To use these, first apply the overlay (instructions below), which will make the packages available in nixpkgs.''' Then you can follow the normal nixpkgs installation instructions (above), but use your package of choice from the overlay (e.g. <code>pkgs.emacsGit</code>) in place of <code>pkgs.emacs</code>. See the [https://github.com/nix-community/emacs-overlay#emacs-overlay README] for a complete list of packages provided, and their differences.


===== With flakes =====
====== With flakes ======
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:<syntaxhighlight lang="nix">
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:<syntaxhighlight lang="nix">
inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";
inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";
Line 273: Line 282:
</syntaxhighlight>
</syntaxhighlight>


=====  Without flakes =====
======  Without flakes ======
For installing one of the unstable branches of Emacs, add the following lines to {{ic|/etc/nixos/configuration.nix}}:
For installing one of the unstable branches of Emacs, add the following lines to {{ic|/etc/nixos/configuration.nix}}:
{{file|configuration.nix|nix|<nowiki>
{{file|configuration.nix|nix|<nowiki>
Line 287: Line 296:
</nowiki>}}
</nowiki>}}


===== 3. Darwin (macOS) =====
===== Darwin (macOS) =====
Nixpkgs provides several of the "Mac Port" versions of Emacs, which have been patched to provide better integration with macOS (see the [https://nixos.org/manual/nixos/stable/index.html#module-services-emacs-releases NixOS manual entry for a full list of packages]). However, those packages typically track the stable releases of Emacs.
Nixpkgs provides several of the "Mac Port" versions of Emacs, which have been patched to provide better integration with macOS (see the [https://nixos.org/manual/nixos/stable/index.html#module-services-emacs-releases NixOS manual entry for a full list of packages]). However, those packages typically track the stable releases of Emacs.


Line 345: Line 354:


A list of official dictionaries for aspell can be found on [https://ftp.gnu.org/gnu/aspell/dict/0index.html  Aspell Website]
A list of official dictionaries for aspell can be found on [https://ftp.gnu.org/gnu/aspell/dict/0index.html  Aspell Website]
== See also ==
* [[Home Manager]] – For declarative Emacs configuration at the user level: [https://nix-community.github.io/home-manager/options.html#opt-programs.emacs.enable Emacs module in Home Manager]
* [https://www.gnu.org/software/emacs/manual/ Emacs Manuals] – Official Emacs documentation.
* [https://search.nixos.org/options?channel=unstable&query=services.emacs NixOS options for Emacs services] – System-level Emacs configuration.
* [https://discourse.nixos.org/search?q=emacs Emacs discussions on NixOS Discourse] – Community tips, troubleshooting, and use cases.
* [[Doom Emacs]] – A popular Emacs configuration framework.
* [https://github.com/nix-community/emacs-overlay Emacs Overlay on Nixpkgs] – For nightly builds and additional Emacs packages.
* [[Text Editor]] – Comparison with other text editors available in NixOS.


== References ==
== References ==
Retrieved from "https://wiki.nixos.org/wiki/Emacs"