Project:GNU Emacs/Developer guide
What is Emacs?
GNU Emacs is the extensible, customizable, self-documenting real-time display editor. Large parts are written in the Lisp dialect Emacs Lisp, with which extensions can be easily developed. Apart from its editing features, GNU Emacs provides a whole environment to manage your system, mail, IRC chats and texts (be it correspondence or programming).
Maintaining the GNU Emacs package
Available versions
Currently the following Emacs versions are available:
| Package | Version | Type | SLOT | eselect name | Remarks |
|---|---|---|---|---|---|
| app-editors/emacs | 18.59 | released | 18 | emacs-18 | For quick editing purposes |
| app-editors/emacs | 26.3 | released | 26 | emacs-26 | |
| app-editors/emacs | 27.2 | released | 27 | emacs-27 | |
| app-editors/emacs | 28.2 | released | 28 | emacs-28 | |
| app-editors/emacs | 29.4 | released | 29 | emacs-29 | |
| app-editors/emacs | 30.0.91 | pretest | 30-vcs | emacs-30-vcs | also .91, .92, ... |
| app-editors/emacs | 30.0.9999 | Git (emacs-30 branch) | 30-vcs | emacs-30-vcs | |
| app-editors/emacs | 31.0.9999 | Git (master branch) | 31-vcs | emacs-31-vcs |
Support of previous versions
We aim to support previous major versions for at least 5 years after a newer version went stable on amd64.
| Major version | Supported until (at least) | Removal |
|---|---|---|
| 18 | indefinitely | |
| 20 | April 2002 | |
| 21 | June 2014 | |
| 22 | June 2014 | |
| 23 | August 2017 | December 2022 |
| 24 | May 2022 | December 2022 |
| 25 | August 2023 | March 2024 |
| 26 | September 2025 | |
| 27 | May 2027 | |
| 28 | September 2028 |
Locations of files
The following files are installed in different locations or under a different name (as compared to vanilla GNU Emacs):
- Emacs executable: /usr/bin/emacs-suffix, where suffix is normally equal to the Emacs major version
- Auxiliary programs (e.g.,
ctags): /usr/bin/ctags-emacs-suffix - Man pages are named accordingly
- Info files of Emacs are installed in directory /usr/share/info/emacs-suffix/
- Game score files are placed in directory /var/games/emacs/
The programs are symlinked to their original names by the Emacs eselect module, apart from ctags and etags which have their own modules.
USE flags
Emacs has many USE flags, most are easy to understand what they are good for, others have some hidden “features” one should know about. The slot for version 18 has only the gui USE flag, so if nothing else is noted, version 23 onwards is described.
| Flag | Description | Introduced in version | Notes |
|---|---|---|---|
| acl | Include support for Access Control Lists. | 24.4 | |
| alsa | Determine if ALSA should be used. | Emacs autodetects ALSA. That test is removed by the ebuild if the flag is not set. This is for cases where ALSA is installed but the user does not wish support for it in Emacs. | |
| aqua | Include support for the Aqua/Cocoa GUI. | Only available under Prefix on Max OS X. | |
| athena | Use the MIT Athena widget set as windowing toolkit. | ||
| cairo | Compile with Cairo drawing. | 25 | package.use.masked for versions 25 and 26. |
| dbus | Make Emacs D-Bus aware. | 23 | |
| dynamic-loading | Loading of dynamic libraries aka emacs modules, using dlopen at runtime. | 25 | |
| games | Support shared score files for games. | This flag is passed on to app-emacs/emacs-common which will install score files. | |
Use gconf to read the system font name.
|
23 | Flag dropped in March 2022 because gnome-base/gconf is deprecated. | |
| gfile | Use gfile (glib) for file notification. | 24.4 | This takes precedence over the inotify flag. Note that glib file notification on Linux uses inotify internally. |
| gif | Support for GIF images. | ||
| gmp | Link against dev-libs/gmp, instead of using the internal mini-gmp lib. | 27 | Enabled by IUSE default. |
| Support GnuTLS for secure session initiation. | 24 | Renamed to ssl.
| |
| gpm | Support for console-based mouse driver. | 23 | |
| gsettings | Use gsettings (glib) to read the system font name. | 24 | |
| gtk | Use the GIMP Toolkit (GTK+) as windowing toolkit (menu bar etc.) | When this toolkit is activated along with alternative ones (see other USE flags), GTK+ is chosen. This is in sync with upstream’s wishes. | |
| Prefer GTK+ version 2 to version 3. | 24 | Dropped in February 2021 because of GTK+ 2 deprecation. | |
| Prefer GTK+ version 3 to version 2. | 24 | Renamed to gtk2 | |
| gui | Let Emacs use a graphical user interface if available. Text mode can always be forced from the command line. | ||
| gzip-el | Zip up all el files.
|
The zip binary is autodetected. So even when this USE flag is disabled but the binary is found, all el files will be compressed. The ebuild takes care of that by confusing the configure script.
| |
| harfbuzz | Use media-libs/harfbuzz as text shaping engine. | 27 | |
| Use the Hesiod name service system. | Dropped in March 2018 because of net-dns/hesiod removal. | ||
| imagemagick | Use the imagemagick toolset for enhanced image manipulation. | 24 | |
| inotify | Enable inotify file change notification support. | 24.4 | |
| jit | Compile with Emacs Lisp native compiler support via libgccjit. | 28 | |
| jpeg | Support for JPEG images. | ||
| json | Compile with native JSON support (dev-libs/jansson). | 27 | |
| kerberos | Support for the Kerberos network authentication protocol. | ||
| lcms | Support for the Little CMS color management engine. | 26 | |
| Extended methods for input encodings. | Emacs 21 only. | ||
| libxml2 | Parse XML with libxml2 instead of built-in Elisp functions which gives a substantial speed-up. | 24 | |
| livecd | Force the /usr/bin/emacs symlink to be set during livecd building. | Internal use, not intended to be set by users. | |
| m17n-lib | Use the m17n-lib multilingual library for complex text layout, e.g. for Indic scripts. | 23 | Only available if xft is enabled too.
|
| mailutils | Rely on GNU Mailutils for movemail support. | 26 | |
| motif | Use Motif as windowing toolkit. | ||
| Enable building under a PaX enabled kernel. | Dropped in April 2018. | ||
| png | Support for PNG images. | ||
| selinux | Support the SELinux security extensions. | 24 | |
| Build with support for mail transfer agent. | Emacs 21 only. | ||
| sound | Control the availability of sound support. | ||
| source | Install the C source files and make them available in the internal documentation system of GNU Emacs. | ||
| sqlite | Support the embedded SQLite database | 29 | |
| ssl | Support SSL/TLS for secure session initiation. | 24 | |
| svg | Support for SVG images. | 23 | |
| systemd | Compile with libsystemd support. | 26 | |
| threads | Add elisp threading support. | 26 | |
| tiff | Support for TIFF images. | ||
| toolkit-scroll-bars | Instead of the internal scroll bars, the ones from the windowing toolkit are used. | You will lose some functionality (split windows by clicking on the scroll bar for example). | |
| tree-sitter | Support the dev-libs/tree-sitter parsing library. | 29 | |
| valgrind | Compile in dev-util/valgrind memory hints. | ||
| webp | Support for WebP images. | 29 | |
| wide-int | Prefer wide Emacs integers, typically 62-bit. | 24 | This option has an effect only on architectures where long and long long types have different size.
|
| X | Support for the X11 window system. | 29 | The original X flag was replaced by gui. Reintroduced in version 29 to distinguish pure GTK from GTK with X11.
|
| xattr | Support extended attributes | 30 | |
| Xaw3d | Use the 3D Athena widget set as windowing toolkit. | ||
| xft | Choose an alternative font renderer. | 23 | |
| xpm | Support for XPM images. | If disabled, all logos, icons etc. in Emacs are displayed in
grayscale. Enabled by IUSE default. | |
| xwidgets | Enable use of some GTK+ widgets in Emacs buffers. | 25 | This flag has an effect only when GTK+ is selected as the windowing toolkit. |
| zlib | Compile with zlib decompression support. | 24.4 |
ChangeLog files
ChangeLog* files for app-editors/emacs are not being installed, because their combined size would be several tens of megabytes (e.g., 29 MiB for Emacs 27.1).
Maintaining Emacs Lisp packages
Depending on a specific Emacs version
The documentation of the functions provided is to be found in the eclasses itself.
A minimum version of GNU Emacs required by a package can be specified by assigning NEED_EMACS=version_number before inheriting elisp.eclass. Without such an assignment, the package will by default depend on >=app-editors/emacs-23.1:*. Packages that have optional support for GNU Emacs (via USE flags) can assign NEED_EMACS as well, and check for a minimum version of GNU Emacs at build time with the elisp-check-emacs-version() function. This check is also implicitly done by elisp-compile(), so an explicit call to elisp-check-emacs-version() isn't strictly necessary if the ebuild uses the eclass functions for compilation.
The site-lisp directory and package loading
The regular location for Emacs lisp packages in Gentoo is /usr/share/emacs/site-lisp/package/. All Elisp files (.el) and compiled Elisp files (.elc) should go there. Any other files should not go there, but must be installed under /usr/share/emacs/etc/package/ instead (see below).
Emacs packages normally need to be activated or loaded when a certain condition is met (like c-mode for C source files).
In Gentoo every package has a site initialisation file that holds the needed commands. The file is located in ${FILESDIR} and starts with a two-digit number, followed by the package name and -gentoo. The elisp-install() function puts this file in the directory /usr/share/emacs/site-lisp/site-gentoo.d/.
When calling elisp-site-regen() in an ebuild, the global site file /usr/share/emacs/site-lisp/site-gentoo.el is regenerated, which holds the contents of all individual site init files in one. They are read in alphabetical order, so the numbers determine which comes first, the lowest is to be found at the beginning. That means: Packages depending on each other need to have rising order for site initialisation, too.
Formerly, all those initialisations were directly added to site-start.el, which is executed at Emacs start-up. Today there is another level of indirection, i.e. initialisations are in /usr/share/emacs/site-lisp/site-gentoo.el which can either be loaded from /etc/emacs/site-start.el (the default), or it can be individually loaded from users’ ~/.emacs files by adding a line like:
(require 'site-gentoo)
Site initialisation means that the package should be ready for use, but not that the package should be imposed on all users by loading or even starting it at Emacs startup time. (Think of systems with multiple users.) A
load command for site initialisations is only acceptable for a few packages. If used, it always loads the whole package and makes Emacs start-up really slow, so the autoload mechanism is the preferred way. The elisp-common eclass has functions to generate an autoload file if none is shipped with the package but the functionality is available in the source nonetheless. For more information about the mechanism see the Elisp manual. Also manual keybindings directly in the site-file are discouraged to not disturb the user as he could have bound exactly that keys himself. Keep pollution low but provide sane default settings out of the box so even a novice can start working fast.The etc directory
In addition to Emacs Lisp files, sometimes packages install other supporting files. These must be installed under /usr/share/emacs/etc/package/. The path is available in the SITEETC variable and the package must of course be told about it; typically, there will be a variable that can be assigned in the site-init file. If the path is hardcoded, patch the package to make it configurable with a variable (and send the patch upstream!).
Eclasses
Packages that have support for or rely on GNU Emacs can use two eclasses to do some recurring tasks in a simple way. The documentation of the functions are provided in the eclasses, so they are not repeated here! Format of documentation is to allow man-page generation from source with the package app-portage/eclass-manpages.
| Name | Purpose |
|---|---|
| elisp-common.eclass | Provides functions to handle Elisp files. Compilation, installation and generation of autoloads is covered here in a general way. Packages with optional Emacs support must rely on this eclass. |
| elisp.eclass | The functions from elisp-common.eclass are used to construct the default functions (src_unpack, src_compile and friends) for packages in the app-emacs hierarchy of ebuilds. It pulls in an appropriate version of Emacs (meaning a version of app-editors/emacs, controlled by the NEED_EMACS variable) and is not intended for packages with optional (via USE flag) support for GNU Emacs.
|
Emacs eselect module
Having several Emacs versions simultaneously installed on a system, needs some caution by maintainers. Usual pitfalls are file collisions and installations of one slot using data from another. As described earlier, the executables are suffixed with their corresponding version number. All data files go to similar directories, also distinguished by a version suffix.
To be independent of the installed version, the eselect module from app-eselect/eselect-emacs guarantees that /usr/bin/emacs always points to the Emacs you want. All ebuilds for the editor check if the symlink is set, and change it to the highest available in the case where it does not exist. If no GNU Emacs is found, but XEmacs, all helper programs are symlinked to the variants shipped with XEmacs.
The module file has some comments about how the code works. For more information how an eselect module is set up, consult the eselect developer guide.
Where Emacs team is upstream
Not all packages maintained by the Emacs team are developed by people from outside the Gentoo project (they are usually called upstream). Most of those exceptions are for proper operation of GNU Emacs in the Gentoo environment.
Sources of these packages are kept in Git (see below). They are released and brought to the Emacs overlay or to the Gentoo repository when they have proven stable.
| Package name | Git repository | Purpose |
|---|---|---|
| app-admin/emacs-updater | proj/emacs-tools | Ships the emacs-updater script, which makes the transition from the old location of the site-init files to the new one. Another purpose is to byte-compile all installed Emacs support files again, e.g. after a major upgrade of Emacs.
|
| app-emacs/ebuild-mode | proj/ebuild-mode | A collection of Emacs major modes that help you edit ebuilds and other Gentoo specific files. This is developed in cooperation with the XEmacs team, so we share the same source. |
| app-emacs/emacs-common | proj/emacs-tools | Installs common files needed by all GNU Emacs versions. These include subdirs.el and a default site-start.el file. With USE=X also desktop files (which provide file associations for many desktop environments) and icons for Emacs and Emacsclient are installed.
|
| app-emacs/emacs-daemon | proj/emacs-tools | Contains the init script to start Emacs as a background service in server mode. The emacsclient executable then uses this to connect to.
|
| app-emacs/nxml-gentoo-schemas | proj/nxml-gentoo-schemas | This extends nxml-mode with some Gentoo specific RELAX NG schemas, so that files like metadata.xml will be automatically validated when editing them.
|
| app-eselect/eselect-ctags | proj/emacs-tools | There are several implementations of the ctags binary, all with a different feature set. This eselect module lets you choose the variant you need.
|
| app-eselect/eselect-emacs | proj/emacs-tools | Setting the correct man page locations, Info documentation paths and target for /usr/bin/emacs, see the separate section. |
A sample ebuild
We present an ebuild that introduces the canonical form regarding variable ordering in global scope and implementation along an example.
# Copyright 1999-2024 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
inherit elisp
DESCRIPTION="ReStructuredText support for Emacs"
HOMEPAGE="http://www.emacswiki.org/cgi-bin/wiki/reStructuredText"
SRC_URI="mirror://sourceforge/docutils/docutils-${PV}.tar.gz"
S="${WORKDIR}/docutils-${PV}/tools/editors/emacs"
LICENSE="GPL-2+"
SLOT="0"
KEYWORDS="amd64 arm64 ppc64"
DOCS="README.txt"
ELISP_PATCHES="${P}-lazy-lock-mode-fix.patch"
SITEFILE="50${PN}-gentoo.el"
The first lines from inherit to KEYWORDS are standard Gentoo ebuild variables and thus outside the scope of this text.
Resources
| Resource | Comment |
|---|---|
| Various authors: Gentoo Development Guide. | Extensive reference about how development is organised in Gentoo, plus style advises for ebuild authors. |
| Robert J. Chassell: An Introduction to Programming in Emacs Lisp. Revised 3rd edition. GNU Press, ISBN 1-882114-43-3. | A primer on Elisp programming (very basic, but very good). |
| Richard M. Stallman: GNU Emacs Manual. 19th edition, for GNU Emacs version 27.2. GNU Press, ISBN 978-0-9831592-8-5. (Online version updated for Emacs 28.1.) | The official handbook of Emacs, also shipped with the editor. This covers the usage of Emacs, not the programming or deep internals. |
| Various authors: GNU Emacs Lisp Reference Manual. | All information needed for Elisp programming, dense and extensive, but not for beginners. |
| Craig A. Finseth: The Craft of Text Editing: Emacs for the Modern World. Springer-Verlag, New York 1991, ISBN 0-387-97616-7. | Background information about user interfaces and the ergonomics of text editing. |