GNU Emacs on Gentoo

1.  Introduction

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

2.  Maintaining the editor itself

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: /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/

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.

3.  Packages

Depending on a specific Emacs version

If a package needs at least a specific version of GNU Emacs, you can tell the elisp.eclass by giving NEED_EMACS=version_number before the inherit line. Undefined the default dependency is on virtual/emacs-21.

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.

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.

Some time ago all those initialisations were added to /usr/share/emacs/site-lisp/site-start.el, which is always loaded at Emacs start-up! Today you can individually control which user will activate all installed Elisp packages by adding a line like

(require 'site-gentoo)

to a file read by Emacs on start-up (usually ~/.emacs).

Historically site-init files were read from the /usr/share/emacs/site-lisp/ directory, which is still supported by the eclasses, but a remerge/update will put them in the site-gentoo.d/ subdirectory. Package app-admin/emacs-updater installs a script that checks for needed rebuilds, called emacs-updater.

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.

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-admin/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 documentation.

Provided virtuals

Sometimes the same functionality is available through different packages. To not force a subjective choice the maintainer made, virtuals check if one of the alternatives is installed on the user's system.

virtual/editor

Just makes sure you have an editing capability available on your system, Emacs is one choice out of many.

virtual/emacs

This gives you the choice between several version of Emacs. Elisp packages can choose which virtual version is the minimum they need through the elisp.eclass.

virtual/flim

There are several libraries that provide encoding functions for other packages. If they are compatible to app-emacs/flim, they should provide the virtual of the same name.

virtual/gnus

The news reader Gnus is shipped with Emacs (from 21 on) and also available as a separate package. To give users a better choice, all of these ebuilds fullfil the virtual, although it is only valid for version 5.10 or greater of Gnus. So the virtual points to Emacs 22.

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 the Emacs SVN repository. They are released and brought to the Emacs overlay or to the Portage tree 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.

# Copyright 1999-2009 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

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"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="alpha amd64 arm hppa ia64 ppc ppc64 s390 sh sparc ~sparc-fbsd x86 ~x86-fbsd"
IUSE=""

S="${WORKDIR}/docutils-${PV}/tools/editors/emacs"
DOCS="README.txt"
SITEFILE="50${PN}-gentoo.el"
PATCHES=( "${FILESDIR}/${P}-lazy-lock-mode-fix.patch" )

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

4.  Resources

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.