Project:GNU Emacs/Developer guide

What is Emacs?
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).

Available versions
Currently the following Emacs versions are available:

Locations of files
The following files are installed in different locations or under a different name (as compared to vanilla GNU Emacs):


 * Emacs executable:, where suffix is normally equal to the Emacs major version
 * Auxiliary programs (e.g., ):
 * Man pages are named accordingly
 * Info files of Emacs are installed in directory
 * Game score files are placed in directory

The programs are symlinked to their original names by the Emacs eselect module, apart from  and   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 no USE flags at all, so if nothing else is noted, version 23 onwards is described.

ChangeLog files
files for are not being installed, because their combined size would be several tens of megabytes (e.g., 29 MiB for Emacs 27.1).

Depending on a specific Emacs version
A minimum version of GNU Emacs required by a package can be specified by assigning  before inheriting. Without such an assignment, the package will by default depend on. Packages that have optional support for GNU Emacs (via USE flags) can assign  as well, and check for a minimum version of GNU Emacs at build time with the   function. This check is also implicitly done by, so an explicit call to   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. All Elisp files and compiled Elisp files  should go there. Any other files should not go there, but must be installed under instead (see below).

Emacs packages normally need to be activated or loaded when a certain condition is met (like  for C source files).

In Gentoo every package has a site initialisation file that holds the needed commands. The file is located in  and starts with a two-digit number, followed by the package name and. The  function puts this file in the directory.

When calling  in an ebuild, the global site file  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, which is executed at Emacs start-up. Today there is another level of indirection, i.e. initialisations are in which can either be loaded from  (the default), or it can be individually loaded from users’  files by adding a line like:

The etc directory
In addition to Emacs Lisp files, sometimes packages install other supporting files. These must be installed under. 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.

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 guarantees that  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.

A sample ebuild
We present an ebuild that introduces the canonical form regarding variable ordering in global scope and implementation along an example.

The first lines from  to KEYWORDS are standard Gentoo ebuild variables and thus outside the scope of this text.