Emacs: Difference between revisions

← Older edit
VisualWikitext
imported>Nodupe
mNo edit summary
Layer-09 (talk | contribs)
64 edits
Changed the structure into a more readable one. Added tree-sitter in the tips and tricks section.
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{Expansion|This article is incomplete.}}
[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.  
== About ==
Emacs is an interactive graphical emacs lisp interpreter that comes with many applications, but is primarily used as a text and code editor. It has one of the largest repositories of packages of any similar code editor such as [[vim]] or its fork [[neovim]].  


=== Features ===
For those seeking a more approachable entry point to the Emacs ecosystem, the [https://github.com/hlissner/doom-emacs 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.
Emacs is often valued as a general purpose programming environment. Its power comes from its
* Extensibility
* Automatic self-documenting behaviour
* Flexibility
* Syntax awareness
* language server protocol support
* potential for reproducible portable literate configurations
 
=== Doom Emacs ===
The [https://github.com/hlissner/doom-emacs Doom Emacs] project provides a framework with a more beginner-friendly default configuration, and pre-configured modules for popular features (e.g. IDE-like features, note-taking, and time management). Since it uses pinning in its configuration for dependencies, it is possible to package Doom Emacs with nix (see [https://github.com/nix-community/nix-doom-emacs nix-doom-emacs]).


== Installation ==
== Installation ==
Several stable versions of emacs are available by default in nixpkgs, and unstable branches are also available via the community overlay. Also, see the [https://nixos.org/manual/nixos/stable/index.html#module-services-emacs NixOS manual entry for Emacs] for additional details about installation and configuration.


=== With Home-Manager ===
==== Using nix-shell ====
{{file|home.nix|nix|<nowiki>
<syntaxhighlight lang="bash" start="3">
{
nix-shell -p emacs
  programs.emacs = {
</syntaxhighlight>
    enable = true;
    package = pkgs.emacs;  # replace with pkgs.emacs-gtk, or a version provided by the community overlay if desired.
    extraConfig = ''
      (setq standard-indent 2)
    '';
  };
}
</nowiki>}}
See the [https://rycee.gitlab.io/home-manager/options.html#opt-programs.emacs.enable Home-Manager manual] for a full list of options.


=== Without Home-Manager ===
==== Using Global Configuration ====
Emacs can be installed in the same way as other packages:
<syntaxhighlight lang="text">
{{file|configuration.nix|nix|<nowiki>
environment.systemPackages = [
{
  pkgs.emacs
  environment.systemPackages = with pkgs; [
];
    emacs # replace with emacs-gtk, or a version provided by the community overlay if desired.
</syntaxhighlight>After modifying your configuration, apply the changes by running:<syntaxhighlight lang="bash">
  ];
sudo nixos-rebuild switch
}
</syntaxhighlight>
</nowiki>}}


=== Enabling the Emacs daemon ===
==== Using Home Configuration ====
Many Emacs users run [https://www.emacswiki.org/emacs/EmacsAsDaemon Emacs as a daemon] and access Emacs via the <code>emacsclient</code> command. NixOS provides a <code>systemd</code> service to facilitate this, which you can enable by adding the following to your <code>configuration.nix</code>:
<syntaxhighlight lang="text">
{{file|configuration.nix|nix|<nowiki>
home.packages = [  
{
  pkgs.emacs  
  services.emacs = {
];
    enable = true;
</syntaxhighlight>After updating your configuration, apply the changes by running:<syntaxhighlight lang="bash">
    package = pkgs.emacs; # replace with emacs-gtk, or a version provided by the community overlay if desired.
home-manager switch
  };
</syntaxhighlight>
}
</nowiki>}}


=== Available Emacs variants ===
== Configuration ==
{{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.}}
{{Note|Currently, configuring Emacs is possible by using Home Manager. A workaround for a global configuration is highlighted in the advanced section.}}


==== Stable (nixpkgs) ====
==== Basic ====
Emacs is available in nixpkgs under the names <code>emacs</code> and <code>emacs-gtk</code>.
<syntaxhighlight lang="nix">
[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).
programs.emacs = {
  enable = true;
  defaultEditor = true;
};
</syntaxhighlight>


==== Unstable (community overlay) ====
==== Advanced ====
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.
<syntaxhighlight lang="nix">
# Global Configuration
# Emacs is running as a daemon here, accesible via the "emacsclient" command
services.emacs = {
  enable = true;
  package = pkgs.emacs;
};


===== With flakes =====
# Home Configuration
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:
programs.emacs = {
  enable = true;
  package = pkgs.emacs;  # replace with pkgs.emacs-gtk if desired
  defaultEditor = true;
  extraConfig = ''
    (setq standard-indent 2)
  '';
};
</syntaxhighlight>


inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";
== Tips and Tricks ==


This can then be used in the system configuration by using the {{ic|self}} argument:
==== Location of Options ====
nixpkgs.overlays = [ (import self.inputs.emacs-overlay) ];
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].


=====  Without flakes =====
The global options are listed on [https://mynixos.com/search?q=nixpkgs%2Foption%2Fservices.emacs MyNixOS].
For installing one of the unstable branches of emacs, add the following lines to {{ic|/etc/nixos/configuration.nix}}:
{{file|configuration.nix|nix|<nowiki>
{
  nixpkgs.overlays = [
    (import (builtins.fetchGit {
      url = "https://github.com/nix-community/emacs-overlay.git";
      ref = "master";
      rev = "bfc8f6edcb7bcf3cf24e4a7199b3f6fed96aaecf"; # change the revision
    }))
  ];
}
</nowiki>}}


=== Darwin (macOS) ===
==== Installing Packages ====
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.
{{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.}}
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;
[ ...
  ((emacsPackagesFor emacsPgtkNativeComp).emacsWithPackages (
    epkgs: [ epkgs.vterm ]
  ))
  ...
];


If you would like to use the latest version of Emacs on Darwin, one option is to use a package like <code>emacsPgkt</code> from the community overlay (see above), and apply patches yourself via an override. For example, here is a derivation that applies the patches from the [https://github.com/d12frosted/homebrew-emacs-plus <code>emacs-plus</code> homebrew formula]:
# To make the packages available to emacsclient, one can do the following:
services.emacs.package = with pkgs; (
  (emacsPackagesFor emacsPgtkNativeComp).emacsWithPackages (
    epkgs: [ epkgs.vterm ]
  )
);


<syntaxhighlight lang="nix">
# Some packages have characters like + that Nix considers a syntax error.  
pkgs.emacsPgtk.overrideAttrs (old: {
# To fix this, write the package name in quotes and specify the package set, even if using with epkgs;.  
      patches =
# For example, use epkgs."ido-completing-read+".
        (old.patches or [])
        ++ [
          # Fix OS window role (needed for window managers like yabai)
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/fix-window-role.patch";
            sha256 = "0c41rgpi19vr9ai740g09lka3nkjk48ppqyqdnncjrkfgvm2710z";
          })
          # Use poll instead of select to get file descriptors
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/poll.patch";
            sha256 = "0j26n6yma4n5wh4klikza6bjnzrmz6zihgcsdx36pn3vbfnaqbh5";
          })
          # Enable rounded window with no decoration
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/round-undecorated-frame.patch";
            sha256 = "111i0r3ahs0f52z15aaa3chlq7ardqnzpwp8r57kfsmnmg6c2nhf";
          })
          # Make Emacs aware of OS-level light/dark mode
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/system-appearance.patch";
            sha256 = "14ndp2fqqc95s70fwhpxq58y8qqj4gzvvffp77snm2xk76c1bvnn";
          })
        ];
    });
  };
}
</syntaxhighlight>


==== Window manager integration ====
Out of the box, non-"Mac Port" versions of Emacs will not be picked up properly by window managers like [https://github.com/koekeishiya/yabai Yabai] because [https://github.com/koekeishiya/yabai/issues/86#issuecomment-507537023 Emacs does not set the correct macOS window role]. This can be fixed with a patch (e.g. the first patch in the example above). However, even with the patch, Yabai may not correctly pick up Emacs if you invoke the <code>emacs</code> binary directly from a shell. For Emacs to work properly with window managers you must invoke it by running the macOS app that is generated when you install Emacs with nix. You can setup an alias to do this like so (replace <code>pkgs.emacs</code> with the package you are using):


{{file|home.nix|nix|<nowiki>
programs.zsh = {
enable = true;
shellAliases = {
  emacs = "${pkgs.emacs}/Applications/Emacs.app/Contents/MacOS/Emacs";
};
};
</nowiki>}}


== 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.}}
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:


environment.systemPackages = with pkgs;
  [ ...
    ((emacsPackagesFor emacsPgtkNativeComp).emacsWithPackages (
      epkgs: [ epkgs.vterm ]
    ))
    ...
  ];


To make the packages available to {{ic|emacsclient}}, one can do the following:
services.emacs.package = with pkgs; (
  (emacsPackagesFor emacsPgtkNativeComp).emacsWithPackages (
    epkgs: [ epkgs.vterm ]
  )
);


Note that some packages may have strange characters like <code>+</code> that would be considered as a syntax error by nix. To avoid that, make sure to write it in quotes and to prepend it with the package set that you want l (even if you used <code>with epkgs; …</code>) like <code>epkgs."ido-completing-read+"</code>.
</syntaxhighlight>[[Emacs]] 29 [[emacswiki:Tree-sitter|supports Tree-sitter parsers]] when built with the <code>--with-tree-sitter</code> option. The <code>emacsPackages.treesit-grammars</code> fake package makes them accessible to Emacs when using <code>emacs29.pkgs.withPackages</code>:<ref>https://github.com/NixOS/nixpkgs/pull/230751</ref><syntaxhighlight lang="nix">
{
  pkgs ? import <nixpkgs> { },
}:
pkgs.emacs29.pkgs.withPackages (epkgs: [
  (epkgs.treesit-grammars.with-grammars (grammars: [ grammars.tree-sitter-bash ]))
])
</syntaxhighlight>


=== Automatic package management ===
==== Automatic Package Management ====
If you use <code>use-package</code> or <code>leaf</code> in your configuration, the community overlay can manage your Emacs packages automatically by using <code>emacsWithPackagesFromUsePackage</code>. First, install the overlay (instructions above), then add the following to your <code>configuration.nix</code>:
If you use <code>use-package</code> or <code>leaf</code> in your configuration, the community overlay can manage your Emacs packages automatically by using <code>emacsWithPackagesFromUsePackage</code>. First, install the overlay (instructions above), then add the following to your <code>configuration.nix</code>:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Line 182: Line 130:
See the [https://github.com/nix-community/emacs-overlay#extra-library-functionality overlay README] for a full list of options.
See the [https://github.com/nix-community/emacs-overlay#extra-library-functionality overlay README] for a full list of options.


=== Adding packages from outside ELPA / MELPA ===
==== Adding packages from outside ELPA / MELPA ====
Some packages may require more sophisticated derivation, but the following is a good starting point for adding external packages:
Some packages may require more sophisticated derivation, but the following is a good starting point for adding external packages:


Line 243: Line 191:
}</nowiki>}}
}</nowiki>}}


=== Packaging and testing emacs nixpkgs ===
==== Packaging and testing emacs nixpkgs ====
Emacs packages can be defined and tested like other nixpkgs.
Emacs packages can be defined and tested like other nixpkgs.
They can be obtained from melpa, elpa or other sources such as github.
They can be obtained from melpa, elpa or other sources such as github.
Line 279: Line 227:
They are located at pkgs/applications/editors/emacs/elisp-packages/manual-packages/ and a new pkg must be added under pkgs/applications/editors/elisp-packages/manual-packages.nix.
They are located at pkgs/applications/editors/emacs/elisp-packages/manual-packages/ and a new pkg must be added under pkgs/applications/editors/elisp-packages/manual-packages.nix.
Once the nixpkg is ready, it can be tested using the following command. This inserts the nixpkg into the load-path of emacs.
Once the nixpkg is ready, it can be tested using the following command. This inserts the nixpkg into the load-path of emacs.
  nix-shell -I nixpkgs=<path_to_nixpkgs_copy> -p "(emacsPackagesFor pkgs.emacs28).emacsWithPackages (epkgs: [ epkgs.<package> ])"
==== Window Manager Integration ====
Out of the box, non-"Mac Port" versions of Emacs will not be picked up properly by window managers like [https://github.com/koekeishiya/yabai Yabai] because [https://github.com/koekeishiya/yabai/issues/86#issuecomment-507537023 Emacs does not set the correct macOS window role]. This can be fixed with a patch (e.g. the first patch in the example above). However, even with the patch, Yabai may not correctly pick up Emacs if you invoke the <code>emacs</code> binary directly from a shell. For Emacs to work properly with window managers you must invoke it by running the macOS app that is generated when you install Emacs with nix. You can setup an alias to do this like so (replace <code>pkgs.emacs</code> with the package you are using):<syntaxhighlight lang="nix">
programs.zsh = {
  enable = true;
  shellAliases = {
    emacs = "${pkgs.emacs}/Applications/Emacs.app/Contents/MacOS/Emacs";
  };
};
</syntaxhighlight>
==== Available Emacs Variants ====
{{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) =====
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).
===== 2. 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.
===== With flakes =====
Using a system flake, one can specify the specific revision of the overlay as a flake input, for example:
inputs.emacs-overlay.url = "github:nix-community/emacs-overlay/da2f552d133497abd434006e0cae996c0a282394";


This can then be used in the system configuration by using the {{ic|self}} argument:
nixpkgs.overlays = [ (import self.inputs.emacs-overlay) ];


   nix-shell -I nixpkgs=<path_to_nixpkgs_copy> -p "(emacsPackagesFor pkgs.emacs28).emacsWithPackages (epkgs: [ epkgs.<package> ])"
=====  Without flakes =====
For installing one of the unstable branches of emacs, add the following lines to {{ic|/etc/nixos/configuration.nix}}:
{{file|configuration.nix|nix|<nowiki>
{
   nixpkgs.overlays = [
    (import (builtins.fetchGit {
      url = "https://github.com/nix-community/emacs-overlay.git";
      ref = "master";
      rev = "bfc8f6edcb7bcf3cf24e4a7199b3f6fed96aaecf"; # change the revision
    }))
  ];
}
</nowiki>}}
 
===== 3. 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.
 
If you would like to use the latest version of Emacs on Darwin, one option is to use a package like <code>emacsPgkt</code> from the community overlay (see above), and apply patches yourself via an override. For example, here is a derivation that applies the patches from the [https://github.com/d12frosted/homebrew-emacs-plus <code>emacs-plus</code> homebrew formula]:
 
<syntaxhighlight lang="nix">
pkgs.emacsPgtk.overrideAttrs (old: {
      patches =
        (old.patches or [])
        ++ [
          # Fix OS window role (needed for window managers like yabai)
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/fix-window-role.patch";
            sha256 = "0c41rgpi19vr9ai740g09lka3nkjk48ppqyqdnncjrkfgvm2710z";
          })
          # Use poll instead of select to get file descriptors
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/poll.patch";
            sha256 = "0j26n6yma4n5wh4klikza6bjnzrmz6zihgcsdx36pn3vbfnaqbh5";
          })
          # Enable rounded window with no decoration
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-29/round-undecorated-frame.patch";
            sha256 = "111i0r3ahs0f52z15aaa3chlq7ardqnzpwp8r57kfsmnmg6c2nhf";
          })
          # Make Emacs aware of OS-level light/dark mode
          (fetchpatch {
            url = "https://raw.githubusercontent.com/d12frosted/homebrew-emacs-plus/master/patches/emacs-28/system-appearance.patch";
            sha256 = "14ndp2fqqc95s70fwhpxq58y8qqj4gzvvffp77snm2xk76c1bvnn";
          })
        ];
    });
  };
}
</syntaxhighlight>


== Bugs ==
== Troubleshooting ==


=== Plasma taskbar grouping ===
==== Plasma taskbar grouping ====
To fix/workaround [[Plasma]] grouping emacs incorrectly (confusing emacs.desktop with emacsclient.desktop), perform the following:
To fix/workaround [[Plasma]] grouping emacs incorrectly (confusing emacs.desktop with emacsclient.desktop), perform the following:
1. open emacs
1. open emacs
Line 297: Line 321:
all emacs instances should now be grouped together, allowing you to pin it and reliably switch to it with Super+<number>
all emacs instances should now be grouped together, allowing you to pin it and reliably switch to it with Super+<number>


=== Spell checking ===
==== Spell checking ====
Because emacs expects the dictionaries to be on the same directory as aspell, they won't be picked up. To fix it install the <code>aspellWithDicts</code> package, specifying the dictionaries you want to use:  
Because emacs expects the dictionaries to be on the same directory as aspell, they won't be picked up. To fix it install the <code>aspellWithDicts</code> package, specifying the dictionaries you want to use:  


Line 310: Line 334:
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]


 
== References ==
 
[[Category:NixOS]]
[[Category:Incomplete]]
[[Category:Applications]]
[[Category:Applications]]
[[Category:NixOS Manual]]
Retrieved from "https://wiki.nixos.org/wiki/Emacs"