Gentoo Development Guide

ELISP-COMMON.ECLASS

Section: portage (5)
Updated: Oct 2014
Index Return to Main Contents
 

NAME

elisp-common.eclass - Emacs-related installation utilities  

DESCRIPTION

Usually you want to use this eclass for (optional) GNU Emacs support of your package. This is NOT for XEmacs!

Many of the steps here are sometimes done by the build system of your package (especially compilation), so this is mainly for standalone elisp files you gathered from somewhere else.

When relying on the emacs USE flag, you need to add

        emacs? ( virtual/emacs )

to your DEPEND/RDEPEND line and use the functions provided here to bring the files to the correct locations.

If your package requires a minimum Emacs version, e.g. Emacs 24, then the dependency should be on >=virtual/emacs-24 instead. Because the user can select the Emacs executable with eselect, you should also make sure that the active Emacs version is sufficient. This can be tested with function elisp-need-emacs(), which would typically be called from pkg_setup(), as in the following example:

        elisp-need-emacs 24 || die "Emacs version too low"

Please note that such tests should be limited to packages that are known to fail with lower Emacs versions; the standard case is to depend on virtual/emacs without version.

 

src_compile() usage:

An elisp file is compiled by the elisp-compile() function defined here and simply takes the source files as arguments. The case of interdependent elisp files is also supported, since the current directory is added to the load-path which makes sure that all files are loadable.

        elisp-compile *.el

Function elisp-make-autoload-file() can be used to generate a file with autoload definitions for the lisp functions. It takes the output file name (default: "${PN}-autoloads.el") and a list of directories (default: working directory) as its arguments. Use of this function requires that the elisp source files contain magic ";;;###autoload" comments. See the Emacs Lisp Reference Manual (node "Autoload") for a detailed explanation.

 

src_install() usage:

The resulting compiled files (.elc) should be put in a subdirectory of /usr/share/emacs/site-lisp/ which is named after the first argument of elisp-install(). The following parameters are the files to be put in that directory. Usually the subdirectory should be ${PN}, you can choose something else, but remember to tell elisp-site-file-install() (see below) the change, as it defaults to ${PN}.

        elisp-install ${PN} *.el *.elc

To let the Emacs support be activated by Emacs on startup, you need to provide a site file (shipped in ${FILESDIR}) which contains the startup code (have a look in the documentation of your software). Normally this would look like this:

        (add-to-list 'load-path "@SITELISP@")
        (add-to-list 'auto-mode-alist '("\.csv\'" . csv-mode))
        (autoload 'csv-mode "csv-mode" "Major mode for csv files." t)

If your Emacs support files are installed in a subdirectory of /usr/share/emacs/site-lisp/ (which is strongly recommended), you need to extend Emacs' load-path as shown in the first non-comment line. The elisp-site-file-install() function of this eclass will replace "@SITELISP@" and "@SITEETC@" by the actual paths.

The next line tells Emacs to load the mode opening a file ending with ".csv" and load functions depending on the context and needed features. Be careful though. Commands as "load-library" or "require" bloat the editor as they are loaded on every startup. When having many Emacs support files, users may be annoyed by the start-up time. Also avoid keybindings as they might interfere with the user's settings. Give a hint in pkg_postinst(), which should be enough. The guiding principle is that emerging your package should not by itself cause a change of standard Emacs behaviour.

The naming scheme for this site-init file matches the shell pattern "[1-8][0-9]*-gentoo*.el", where the two digits at the beginning define the loading order (numbers below 10 or above 89 are reserved for internal use). So if your initialisation depends on another Emacs package, your site file's number must be higher! If there are no such interdependencies then the number should be 50. Otherwise, numbers divisible by 10 are preferred.

Best practice is to define a SITEFILE variable in the global scope of your ebuild (e.g., right after S or RDEPEND):

        SITEFILE="50${PN}-gentoo.el"

Which is then installed by

        elisp-site-file-install "${FILESDIR}/${SITEFILE}"

in src_install(). Any characters after the "-gentoo" part and before the extension will be stripped from the destination file's name. For example, a file "50${PN}-gentoo-${PV}.el" will be installed as "50${PN}-gentoo.el". If your subdirectory is not named ${PN}, give the differing name as second argument.

 

pkg_postinst() / pkg_postrm() usage:

After that you need to recreate the start-up file of Emacs after emerging and unmerging by using

        pkg_postinst() {
                elisp-site-regen
        }

        pkg_postrm() {
                elisp-site-regen
        }

When having optional Emacs support, you should prepend "use emacs &&" to above calls of elisp-site-regen(). Don't use "has_version virtual/emacs"! When unmerging the state of the emacs USE flag is taken from the package database and not from the environment, so it is no problem when you unset USE=emacs between merge and unmerge of a package.  

FUNCTIONS

elisp-emacs-version
Output version of currently active Emacs.

Return value: exit status of Emacs

elisp-need-emacs <version>
Test if the eselected Emacs version is at least the major version of GNU Emacs specified as argument.

Return value: 0 if true, 1 if false, 2 if trouble

elisp-compile <list of elisp files>
Byte-compile Emacs Lisp files.

This function uses GNU Emacs to byte-compile all ".el" specified by its arguments. The resulting byte-code (".elc") files are placed in the same directory as their corresponding source file.

The current directory is added to the load-path. This will ensure that interdependent Emacs Lisp files are visible between themselves, in case they require or load one another.

elisp-make-autoload-file [output file] [list of directories]
Generate a file with autoload definitions for the lisp functions.
elisp-install <subdirectory> <list of files>
Install files in SITELISP directory.
elisp-site-file-install <site-init file> [subdirectory]
Install Emacs site-init file in SITELISP directory. Automatically inserts a standard comment header with the name of the package (unless it is already present). Tokens @SITELISP@ and @SITEETC@ are replaced by the path to the package's subdirectory in SITELISP and SITEETC, respectively.
elisp-site-regen
Regenerate the site-gentoo.el file, based on packages' site initialisation files in the /usr/share/emacs/site-lisp/site-gentoo.d/ directory.
 

ECLASS VARIABLES

SITELISP = /usr/share/emacs/site-lisp
Directory where packages install Emacs Lisp files.
SITEETC = /usr/share/emacs/etc
Directory where packages install miscellaneous (not Lisp) files.
EMACS = ${EPREFIX}/usr/bin/emacs
Path of Emacs executable.
EMACSFLAGS = "-batch -q --no-site-file"
Flags for executing Emacs in batch mode. These work for Emacs versions 18-24, so don't change them.
BYTECOMPFLAGS = "-L ."
Emacs flags used for byte-compilation in elisp-compile().
 

AUTHORS

Matthew Kennedy <mkennedy@gentoo.org>
Jeremy Maitin-Shepard <jbms@attbi.com>
Mamoru Komachi <usata@gentoo.org>
Christian Faulhammer <fauli@gentoo.org>
Ulrich Müller <ulm@gentoo.org>
 

MAINTAINERS

Gentoo Emacs team <emacs@gentoo.org>
 

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/  

FILES

/usr/portage/eclass/elisp-common.eclass  

SEE ALSO

ebuild(5)
http://sources.gentoo.org/eclass/elisp-common.eclass?view=log


 

Index

NAME
DESCRIPTION
src_compile() usage:
src_install() usage:
pkg_postinst() / pkg_postrm() usage:
FUNCTIONS
ECLASS VARIABLES
AUTHORS
MAINTAINERS
REPORTING BUGS
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 03:25:03 GMT, October 23, 2014