Gentoo Development Guide


Section: portage (5)
Updated: Nov 2015
Index Return to Main Contents


xemacs-elisp-common.eclass - XEmacs-related installation utilities  


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

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 xemacs USE flag, you need to add

      xemacs? ( app-editors/xemacs )

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


src_compile() usage:

An elisp file is compiled by the xemacs-elisp-compile() function defined here and simply takes the source files as arguments.

  xemacs-elisp-compile *.el

In the case of interdependent elisp files, you can use the xemacs-elisp-comp() function which makes sure all files are loadable.

  xemacs-elisp-comp *.el

Function xemacs-elisp-make-autoload-file() can be used to generate a file with autoload definitions for the lisp functions. It takes a list of directories (default: working directory) as its argument. Use of this function requires that the elisp source files contain magic ";;;###autoload" comments. See the XEmacs 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/lib/xemacs/site-lisp/ which is named after the first argument of xemacs-elisp-install(). The following parameters are the files to be put in that directory. Usually the subdirectory should be ${PN}, but you can choose something else.

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

To let the XEmacs support be activated by XEmacs 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 XEmacs support files are installed in a subdirectory of /usr/share/xemacs/site-packages/ (which is strongly recommended), you need to extend XEmacs' load-path as shown in the first non-comment line. The xemacs-elisp-site-file-install() function of this eclass will replace "@SITELISP@" by the actual path.

The next line tells XEmacs 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 XEmacs 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 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 XEmacs 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):


Which is then installed by

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

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.  


xemacs-elisp-compile <list of elisp files>
Byte-compile elisp files with xemacs. This function will die when there is a problem compiling the lisp files.
xemacs-elisp-install <subdirectory> <list of files>
Install elisp source and byte-compiled files. All files are installed in site-packages in their own directory, indicated by the first argument to the function. This function will die if there is a problem installing the list files.
xemacs-elisp-comp <list of elisp files>
Byte-compile interdependent XEmacs lisp files. Originally taken from GNU autotools, but some configuration options removed as they don't make sense with the current status of XEmacs in Gentoo.
xemacs-elisp-site-file-install <site-init file> [subdirectory]
Install XEmacs site-init file in XEMACS_SITELISP directory. Automatically inserts a standard comment header with the name of the package (unless it is already present). Token @SITELISP@ is replaced by the path to the package's subdirectory in XEMACS_SITELISP.
Regenerate the site-gentoo.el file, based on packages' site initialisation files in the /usr/share/xemacs/site-lisp/site-gentoo.d/ directory.


XEMACS_SITELISP = /usr/share/xemacs/site-lisp
Directory where packages install indivivual XEmacs Lisp files.
XEMACS_SITEPACKAGE = /usr/share/xemacs/site-packages
Directory where packages install XEmacs Lisp packages.
XEMACS = /usr/bin/xemacs
Path of XEmacs executable.
XEMACS_BATCH_CLEAN = "${XEMACS} --batch --no-site-file --no-init-file"
Invocation of XEMACS in batch mode.



Please report bugs via  







src_compile() usage:
src_install() usage:

This document was created by man2html, using the manual pages.
Time: 03:25:02 GMT, November 26, 2015