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 Detailed developer information can be found on the project page.


USE flags

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

X Add support for X11
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
gmp Use the GNU multiple precision arithmetic library (dev-libs/gmp) instead of the bundled mini-gmp subset
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
inotify Enable inotify filesystem monitoring support
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 sqliteembedded 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
threads Add elisp threading support
tiff Add support for the TIFF image format
toolkit-scroll-bars Use the selected toolkit's scrollbars in preference to Emacs' own scrollbars
webp Add support for the WebP image format
wide-int Prefer wide Emacs integers (typically 62-bit). This option has an effect only on architectures where "long" and "long long" types have different size.
xft Build with support for XFT font renderer (x11-libs/libXft)
xpm Add support for XPM graphics format
xwidgets Enable use of GTK widgets in Emacs buffers (requires GTK3)
zlib Add support for zlib (de)compression


root #emerge --ask app-editors/emacs

For Xorg or Wayland at least USE="gui gtk" required.

USE flags for toolkits gtk, motif, athena, and aqua are mutually exclusive. Generally, USE="gtk" is a good choice if you have one display. However, if intending to use Emacs as a daemon, USE="motif -athena -gtk -Xaw3d" or USE="athena Xaw3d -gtk -motif" is recommended instead because of bug #292471. USE="athena Xaw3d" resembles USE="gtk" very well. USE="aqua" is a special case applying only to Mac OS X.

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.


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 file ~/.emacs is not automatically created on installation or on first invocation, though the directory ~/.emacs.d can be.



Customization is available via /etc/conf.d/emacs.

Gentoo provides OpenRC init scripts for Emacs in the package 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


With systemd, simply enable the upstream user unit:

user $systemctl --user enable --now emacs

Builtin method

User can also start 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
If user starts 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.


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).


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).

Additional elisp packages

Emacs has lots of additional packages written in elisp. There is a number of ways to install them, but the standard one is package.el nowadays. On Gentoo it can be used both on per-user and system-wide way.

To install elisp packages per-user use package.el distributed with GNU Emacs.

To install elisp packages system-wide under the Portage control you can use gs-elpa. Read layman documentation before using it, as gs-elpa represents ELPA repositories as g-sorcery overlays. It currently supports 4 repositories: gnu-elpa, marmalade, melpa and melpa-stable.

When the layman setup works, install gs-elpa:

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

After it you can start adding elisp repos and emerging packages, e.g.:

root #layman -L
root #layman -a gnu-elpa
root #layman -a melpa-stable
root #emerge --ask app-emacs/starter-kit app-emacs/starter-kit-bindings app-emacs/starter-kit-eshell app-emacs/starter-kit-lisp
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 you ever find bugs like this one, you can exclude packages 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