GNU Emacs

From Gentoo Wiki
Jump to:navigation Jump to:search

GNU Emacs is a powerful, extensible, self-documenting text editor. It is released by the Free Software Foundation and has been under development since 1976.

In Gentoo, GNU Emacs is maintained by the team of the same name, which can be reached through gnu-emacs@gentoo.org. Detailed developer information can be found on the project page.

Installation

USE flags

Note
Some packages have the emacs USE flag set, which usually adds emacs-related functionality.

USE flags for app-editors/emacs The extensible, customizable, self-documenting real-time display editor

+X Add support for X11
+gmp Use the GNU multiple precision arithmetic library (dev-libs/gmp) instead of the bundled mini-gmp subset
+inotify Enable inotify filesystem monitoring support
+threads Add elisp threading support
+xpm Add support for XPM graphics format
Xaw3d Add support for the 3d athena widget set
acl Add support for Access Control Lists
alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
aqua Include support for the Mac OS X Aqua (Carbon/Cocoa) GUI
athena Enable the MIT Athena widget set (x11-libs/libXaw)
cairo Enable support for the cairo graphics library
dbus Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc)
dynamic-loading Enable loading of dynamic libraries (modules) at runtime
games Support shared score files for games
gfile Use gfile (dev-libs/glib) for file notification
gif Add GIF image support
gpm Add support for sys-libs/gpm (Console-based mouse driver)
gsettings Use gsettings (dev-libs/glib) to read the system font name
gtk Add support for x11-libs/gtk+ (The GIMP Toolkit)
gui Enable support for a graphical user interface
gzip-el Compress bundled Emacs Lisp source
harfbuzz Use media-libs/harfbuzz as text shaping engine
imagemagick Use media-gfx/imagemagick for image processing
jit Compile with Emacs Lisp native compiler support via libgccjit
jpeg Add JPEG image support
json Compile with native JSON support using dev-libs/jansson
kerberos Add kerberos support
lcms Add lcms support (color management engine)
libxml2 Use dev-libs/libxml2 to parse XML instead of the internal Lisp implementations
livecd !!internal use only!! DO NOT SET THIS FLAG YOURSELF!, used during livecd building
m17n-lib Enable m17n-lib support
mailutils Retrieve e-mail using net-mail/mailutils instead of the internal movemail substitute
motif Add support for the Motif toolkit
png Add support for libpng (PNG images)
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
sound Enable sound support
source Install C source files and make them available for find-function
sqlite Add support for sqlite - embedded sql database
ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
svg Add support for SVG (Scalable Vector Graphics)
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
tiff Add support for the TIFF image format
toolkit-scroll-bars Use the selected toolkit's scrollbars in preference to Emacs' own scrollbars
tree-sitter Support the dev-libs/tree-sitter parsing library
valgrind Enable annotations for accuracy. May slow down runtime slightly. Safe to use even if not currently using dev-debug/valgrind
webp Add support for the WebP image format
wide-int Prefer wide Emacs integers (typically 62-bit). This option has an effect only on 32-bit systems, where it increases the maximum buffer size from 0.5 to 2 GiB, at the cost of 10% to 30% Lisp slowdown.
xattr Add support for extended attributes (filesystem-stored metadata)
xft Build with support for XFT font renderer (x11-libs/libXft)
zlib Add support for zlib compression
Data provided by the Gentoo Package Database · Last update: 2024-10-31 06:05 More information about USE flags

USE="mailutils" is encouraged for e-mail features.

For Xorg or Wayland, at least USE="gui gtk" is required. After Emacs 29 on Wayland, bug #831154 recommends USE="-X gtk" enabled "pure GTK mode".

Toolkit USE flags are mutually exclusive, so enable only one of: gtk, motif, athena, or aqua.

  • USE="aqua" only applies to macOS.
  • USE="gtk" is generally good for systems with one display.
  • Multiple displays may USE="motif -gtk".
  • USE="athena Xaw3d" resembles gtk very well.
  • To use Emacs as a daemon only, bug #292471 recommends USE="motif -athena -Xaw3d -gtk" or USE="athena Xaw3d -motif -gtk".


JIT

Emacs can use gcc to compile Emacs Lisp code to native binaries (they have .eln suffix) which gives a nice performance boost.

To use it, activate the jit USE flag for app-editors/emacs and sys-devel/gcc:

FILE /etc/portage/package.use
app-editors/emacs jit
sys-devel/gcc jit

Then complete a world upgrade for these changes to take effect:

root #emerge --ask --update --changed-use @world
Note
The Gentoo ebuild compiles the whole emacs distribution Lisp code: https://www.emacswiki.org/emacs/GccEmacs#h5o-15
Note
Emacs packages do not yet handle JIT by themselves: bug #735148.


PGTK

Emacs can be built to the use "pgtk" (Pure GTK) frontend: Emacs will no longer use X11 APIs directly, instead it only uses GTK (and Cairo), hence (in theory) any platform supported by GTK, such as Wayland (without the need for XWayland).

To activate pgtk, disable the X USE flag and enable gui and gtk for app-editors/emacs:

FILE /etc/portage/package.use
app-editors/emacs gui gtk -X

Then run:

root #emerge --ask --update --changed-use @world

This will also get rid of the annoying warning of: 

Warning: due to a long standing Gtk+ bug
http://bugzilla.gnome.org/show_bug.cgi?id=85715
Emacs might crash when run in daemon mode and the X11 connection is unexpectedly lost.
Using an Emacs configured with --with-x-toolkit=lucid does not have this problem.

SSL

To use Emacs for ERC or when desiring to download packages from ELPA/MELPA via Emacs, it is wise to compile with the ssl USE flag. Emacs will use the program gnutls-cli (provided by net-libs/gnutls), but only when it is also compiled with the tools USE flag. The tools USE flag is not enabled by default.

Emerge

To install Emacs, run:

root #emerge --ask app-editors/emacs

Several versions side-by-side

In Gentoo, several Emacs versions can be installed on a system simultaneously. The upstream version already installs elisp and data files into versioned subdirectories. To avoid file collisions between slots, in Gentoo binaries and man pages are suffixed with their corresponding version number, too.

The eselect module from app-eselect/eselect-emacs can be used to link /usr/bin/emacs and its auxiliary programs to the ones belonging to the desired Emacs version. Consult the eselect user guide for details on eselect.

Configuration

Emacs can be customized by clicking through the GUI (use M-x customize-group RET).

Emacs can also be configured by using the ~/.emacs configuration file, which is written in Emacs Lisp, Emacs' own Lisp dialect. The ~/.emacs file is not automatically created on installation or on first invocation, though the directory ~/.emacs.d can be.

Daemon

OpenRC

Tip
Customization is available via /etc/conf.d/emacs and /etc/conf.d/emacs.<user>

Gentoo provides OpenRC init scripts for Emacs in the package app-emacs/emacs-daemon:

root #emerge --ask app-emacs/emacs-daemon

First, create a symlink for at least one user in /etc/init.d:

root #ln -s /etc/init.d/emacs /etc/init.d/emacs.myuser

Then add it to the appropriate runlevel:

root #rc-update add emacs.myuser default

Finally, start up the new Emacs service:

root #/etc/init.d/emacs.myuser start

Usually, an Emacs server socket will be created for emacsclient to connect to. If the XDG_RUNTIME_DIR variable is set at the time the Emacs server is started, the socket will be /run/user/<user_id>/emacs/server. If that variable is not set at the time the Emacs server is started, the socket will be created at /tmp/emacs<user_id>/server, e.g. /tmp/emacs1000/server. To use emacsclient with this socket, use the -s / --socket-name option, e.g.:

user $emacsclient --socket-name='/tmp/emacs1000/server'
Warning
Starting an Emacs server during boot, and thus in the absence of a D-Bus session bus, will mean the DBUS_SESSION_BUS_ADDRESS environment variable is not set appropriately within the server's environment. This might cause various issues, e.g. Emacs unable to opening a new tab in an existing Firefox instance. To fix this, add the following shell command to the startup file of your window manager or desktop environment (using the --socket-name option if necessary):
CODE 
emacsclient --eval "(progn (setenv \"DBUS_SESSION_BUS_ADDRESS\" \"${DBUS_SESSION_BUS_ADDRESS}\")  (dbus-init-bus))"
Note that Emacs 28.2 and earlier have an issue where this use of setenv would not work; this has been fixed in commit 1383efe01d of 2023-06-12. The fix has been applied to app-editors/emacs-{28.2-r9,28.3_rc1-r4} and later.
Warning
Wayland users will also need to manually set the WAYLAND_DISPLAY variable. To do so, add the following shell command to the startup file of your window manager or desktop environment (using the --socket-name option if necessary):
CODE 
emacsclient --eval "(setenv \"WAYLAND_DISPLAY\" \"${WAYLAND_DISPLAY}\")"

systemd

With systemd, simply enable the upstream user unit:

user $systemctl --user enable --now emacs-28

Builtin method

The user can also start the daemon inside an already running instance of emacs. For that, type M-x server-start RET (that is, Meta, or Alt, followed by x server-start, and finally Enter).

Connect to emacs daemon

user $emacsclient --socket-name=/tmp/emacs$(id -u)/server file
Tip
If user starts the daemon inside emacs, everything works out-of-the-box. Otherwise, in order to save typing while connecting to the emacs daemon, export EMACS_SOCKET_NAME in a user's profile file, as in the example above. See bug #794649. This method also guarantees that exporting EDITOR=emacsclient will work as expected.

Usage

Exiting Emacs

For beginners who don't know the key combinations, it may be difficult to exit Emacs. To close Emacs, type C-x C-c (Ctrl+x followed by Ctrl+c).

Documentation

For a quick-start documentation, type in Emacs: C-h t (Ctrl+h followed by t). For further help on how to use Emacs, start emacs and type C-h r (Ctrl+h followed by r).

Starter Kits

Since Emacs supports so many features and additional packages, configuration and customization can become cumbersome, an Emacs distribution may help starting out. They aim to provide a "batteries included" approach and plug together many features and packages automatically:

Vim controls

Contrary to popular belief, many Emacs users prefer to get the best out of "both worlds". To do so, Vim and Emacs features can be combined (and used alongside), for example, with Evil.

Spacemacs and Doom support this out of the box.

Additional elisp packages

Emacs has lots of additional packages written in elisp.

Users have two choices:

  1. If installing packages per-user, package.el is recommended. Other methods exist too such as straight.el and Elpaca.
  2. If installing packages through the system's package manager is preferred, then only emerge is needed. gs-elpa can be used to create ebuilds if one does not already exist for a needed package.

gs-elpa is a tool to generate ebuilds for elisp packages where no ebuild already exists.

To install elisp packages system-wide under Portage's control, use gs-elpa. Read eselect-repository documentation before using it, as gs-elpa represents ELPA repositories as g-sorcery overlays.

It currently supports 4 repositories:

  1. gnu-elpa
  2. marmalade
  3. melpa
  4. melpa-stable

Once eselect repository is setup, install gs-elpa:

root #emerge --ask app-portage/gs-elpa

Start adding elisp repos and emerging packages, e.g.:

root #eselect repository list
root #eselect repository enable gnu-elpa
root #eselect repository enable melpa-stable
root #emerge --ask app-emacs/starter-kit app-emacs/starter-kit-bindings app-emacs/starter-kit-eshell app-emacs/starter-kit-lisp
Warning
Always add the gnu-elpa repository first, as other repos depend on it.

Bugs related to gs-elpa should be reported on its issue tracker.

If bugs like this are encountered, packages can be excluded from dependencies adding their name to the "external" object in the "common-config" section of /etc/g-sorcery/gs-elpa.json configuration file. For the example issue, it would be (together with already added packages):

FILE /etc/g-sorcery/gs-elpa.json
"external": {"emacs": "virtual/emacs", "cl-lib": "virtual/emacs", "eieio": "virtual/emacs"}

See also

Retrieved from "https://wiki.gentoo.org/index.php?title=GNU_Emacs&oldid=1310322"