Gentoo Development Guide

XEMACS-ELISP-COMMON.ECLASS

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

NAME

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

DESCRIPTION

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


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

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.  

FUNCTIONS

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.
xemacs-elisp-site-regen
Regenerate the site-gentoo.el file, based on packages' site initialisation files in the /usr/share/xemacs/site-lisp/site-gentoo.d/ directory.
 

ECLASS VARIABLES

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.
 

MAINTAINERS

xemacs@gentoo.org
 

REPORTING BUGS

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

FILES

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

SEE ALSO

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


 

Index

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

This document was created by man2html, using the manual pages.
Time: 03:25:04 GMT, November 27, 2014