ELISP-COMMON.ECLASS

Section: eclass-manpages (5)
Updated: Nov 2024
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? ( >=app-editors/emacs-25.3:* )

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 26.1, then the dependency should be on >=app-editors/emacs-26.1:* instead. Because the user can select the Emacs executable with eselect, you should also make sure that the active Emacs version is sufficient. The eclass will automatically ensure this if you assign variable NEED_EMACS with the Emacs version, as in the following example:

        NEED_EMACS=26.1

Please note that this should be done only for packages that are known to fail with lower Emacs versions.

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.

For the simple case that only the package's subdirectory needs to be added to the load-path, function elisp-make-site-file() will create and install a site-init file that does just that:

        elisp-make-site-file "${SITEFILE}"

Again, this must be called in src_install(). See the function's documentation for more details on its usage.

pkg_setup() usage:

If your ebuild uses the elisp-compile eclass function to compile its elisp files (see above), then you don't need a pkg_setup phase, because elisp-compile and elisp-make-autoload-file do their own sanity checks. On the other hand, if the elisp files are compiled by the package's build system, then there is often no check for the Emacs version. In this case, you can add an explicit check in pkg_setup:

        elisp-check-emacs-version

When having optional Emacs support, you should prepend "use emacs &&" to above call of elisp-check-emacs-version().

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
        }

Again, with optional Emacs support, you should prepend "use emacs &&" to above calls of elisp-site-regen().

SUPPORTED EAPIS

7 8

FUNCTIONS

elisp-emacs-version

Output version of currently active Emacs.

Return value: exit status of Emacs

elisp-check-emacs-version [version]

Test if the eselected Emacs version is at least the version of GNU Emacs specified in the NEED_EMACS variable, or die otherwise.

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-org-export-to <export file type> <Org file path>

Use Emacs Org "export-to" functions to convert a given Org file to a picked format.

Example:

        elisp-org-export-to texinfo README.org
        mv README.texi ${PN}.texi || die

elisp-test-buttercup [test-subdirectory] [test-runner-opts] ...

Run ELisp package tests using the "buttercup" test runner.

The option "test-subdirectory" may be given any number of times, it should be given as though it was passed to Emacs or the test tool, not as a string.

The options "test-subdirectory" and "test-runner-opts" are optional, but if "test-runner-opts" needs to be provided also "test-subdirectory" has to be specified.

elisp-test-ert-runner [test-subdirectory] [test-runner-opts] ...

Run ELisp package tests using the "ert-runner" test runner.

The option "test-subdirectory" may be given any number of times, it should be given as though it was passed to Emacs or the test tool, not as a string.

The options "test-subdirectory" and "test-runner-opts" are optional, but if "test-runner-opts" needs to be provided also "test-subdirectory" has to be specified.

elisp-test-ert [test-subdirectory] [test-runner-opts] ...

Run ELisp package tests using "ert", the Emacs's built-in test runner.

The option "test-subdirectory" may be given any number of times, it should be given as though it was passed to Emacs or the test tool, not as a string.

The options "test-subdirectory" and "test-runner-opts" are optional, but if "test-runner-opts" needs to be provided also "test-subdirectory" has to be specified.

elisp-enable-tests [--optional] <test-runner> [test-runner-options] ...

Set up IUSE, RESTRICT, BDEPEND and test runner function for running tests with the specified test runner.

The test-runner argument must be one of:

- buttercup: for "buttercup" provided via "app-emacs/buttercup"

- ert-runner: for "ert-runner" provided via "app-emacs/ert-runner"

- ert: for built-in GNU Emacs test utility

If the "--optional" flag is passed (before specifying the test runner), then it is assumed that the ELisp package is a part of some some project that optionally enables GNU Emacs support. This will correctly set up the test and Emacs dependencies.

Notice that the first option passed to the "test-runner" is the directory and the rest are miscellaneous options applicable to that given runner.

This function has to be called post inherit, specifically after "IUSE", "RESTRICT" and "BDEPEND" variables are assigned. It is advised to place this call right before (re)defining a given ebuild's phases.

Example:

        inherit elisp-common

        ...

        elisp-enable-tests --optional ert-runner "${S}"/elisp -t "!org"

        src_test() {
                emake -C tests test
                elisp-test
        }

elisp-test

Test the package using a ELisp test runner.

If called without executing "elisp-enable-tests" beforehand, then does nothing, otherwise a test runner is called with given "test-runner-options".

elisp-install <subdirectory> <list of files>

Install files in SITELISP directory.

elisp-modules-install <subdirectory> <list of files>

Install dynamic modules in EMACSMODULES 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@, @SITEETC@, and @EMACSMODULES@ are replaced by the path to the package's subdirectory in SITELISP, SITEETC, and EMACSMODULES, respectively.

elisp-make-site-file <filename> [subdirectory] [line]...

Create and install a site-init file for the package. By default, this will add the package's SITELISP subdirectory to Emacs' load-path:

        (add-to-list 'load-path "@SITELISP@")

Additional arguments are appended as lines to the destination file. Any @SITELISP@, @SITEETC@, and @EMACSMODULES@ tokens in these arguments are replaced, as described for elisp-site-file-install.

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.
EMACSMODULES = /usr/@libdir@/emacs/modules: Directory where packages install dynamically loaded modules. May contain a @libdir@ token which will be replaced by $(get_libdir).
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().
NEED_EMACS ?= 25.3: The minimum Emacs version required for the package.