gentoo-x86/eclass/elisp-common.eclass

# Copyright 1999-2007 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: /var/cvsroot/gentoo-x86/eclass/elisp-common.eclass,v 1.27 2007/08/27 19:41:03 ulm Exp $
#
# Copyright 2007 Christian Faulhammer <opfer@gentoo.org>
# Copyright 2002-2004 Matthew Kennedy <mkennedy@gentoo.org>
# Copyright 2004-2005 Mamoru Komachi <usata@gentoo.org>
# Copyright 2003 Jeremy Maitin-Shepard <jbms@attbi.com>
# Copyright 2007 Ulrich Mueller <ulm@gentoo.org>
#
# @ECLASS: elisp-common.eclass
# @MAINTAINER:
# Feel free to contact the Emacs team through emacs@gentoo.org if you have
# problems, suggestions or questions.
# @BLURB: 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.
#
# .SS
# src_compile() usage:
#
# An elisp file is compiled by the elisp-compile() function defined here and
# simply takes the source files as arguments.
#
#       elisp-compile *.el || die "elisp-compile failed"
#
# In the case of interdependent elisp files, you can use the elisp-comp()
# function which makes sure all files are loadable.
#
#       elisp-comp *.el || die "elisp-comp failed"
#
# 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.
#
# .SS
# 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 || die "elisp-install failed"
#
# 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:
#
#       ;;; csv-mode site-lisp configuration
#
#       (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 recommended if more than one file is
# installed), you need to extend Emacs' load-path as shown in the first
# non-comment.  The elisp-site-file-install() function of this eclass will
# replace "@SITELISP@" by the actual path.
#
# 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 a lot of 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 naming scheme for this site file is "[0-9][0-9]*-gentoo.el", where the
# two digits at the beginning define the loading order.  So if you depend on
# another Emacs package, your site file's number must be higher!
#
# Best practice is to define a SITEFILE variable in the global scope of your
# ebuild (right after DEPEND e.g.):
#
#       SITEFILE=50${PN}-gentoo.el
#
# Which is then installed by
#
#       elisp-site-file-install "${FILESDIR}/${SITEFILE}"
#
# in src_install().  If your subdirectory is not named ${PN}, give the
# differing name as second argument.
#
# .SS
# 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.
#
# .SS
# Miscellaneous functions:
#
# elisp-emacs-version() outputs the version of the currently active Emacs.

SITELISP=/usr/share/emacs/site-lisp
SITEFILE=50${PN}-gentoo.el
EMACS=/usr/bin/emacs
# The following works for Emacs versions 18-23, don't change it.
EMACS_BATCH_CLEAN="${EMACS} -batch -q --no-site-file"

# @FUNCTION: elisp-compile
# @USAGE: <list of elisp files>
# @DESCRIPTION:
# Byte-compile Emacs Lisp files.

elisp-compile() {
        einfo "Compiling GNU Emacs Elisp files ..."
        ${EMACS_BATCH_CLEAN} -f batch-byte-compile "$@"
}

# @FUNCTION: elisp-emacs-version
# @DESCRIPTION:
# Output version of currently active Emacs.

elisp-emacs-version() {
        # The following will work for at least versions 18-23.
        echo "(princ emacs-version)" >"${T}"/emacs-version.el
        ${EMACS_BATCH_CLEAN} -l "${T}"/emacs-version.el
}

# @FUNCTION: elisp-make-autoload-file
# @USAGE: [output file] [list of directories]
# @DESCRIPTION:
# Generate a file with autoload definitions for the lisp functions.

elisp-make-autoload-file () {
        local f="${1:-${PN}-autoloads.el}"
        shift
        einfo "Generating autoload file for GNU Emacs ..."

        sed 's/^FF/\f/' >"${f}" <<-EOF
        ;;; ${f##*/} --- autoloads for ${P}

        ;;; Commentary:
        ;; Automatically generated by elisp-common.eclass
        ;; DO NOT EDIT THIS FILE

        ;;; Code:
        FF
        ;; Local Variables:
        ;; version-control: never
        ;; no-byte-compile: t
        ;; no-update-autoloads: t
        ;; End:
        ;;; ${f##*/} ends here
        EOF

        ${EMACS_BATCH_CLEAN} \
                --eval "(setq make-backup-files nil)" \
                --eval "(setq generated-autoload-file (expand-file-name \"${f}\"))" \
                -f batch-update-autoloads "${@-.}"
}

# @FUNCTION: elisp-install
# @USAGE: <subdirectory> <list of files>
# @DESCRIPTION:
# Install files in SITELISP directory.

elisp-install() {
        local subdir="$1"
        shift
        einfo "Installing Elisp files for GNU Emacs support ..."
        ( # subshell to avoid pollution of calling environment
                insinto "${SITELISP}/${subdir}"
                doins "$@"
        )
}

# @FUNCTION: elisp-site-file-install
# @USAGE: <site-init file> [subdirectory]
# @DESCRIPTION:
# Install Emacs site-init file in SITELISP directory.

elisp-site-file-install() {
        local sf="$1" my_pn="${2:-${PN}}"
        einfo "Installing site initialisation file for GNU Emacs ..."
        cp "${sf}" "${T}"
        sed -i "s:@SITELISP@:${SITELISP}/${my_pn}:g" "${T}/$(basename "${sf}")"
        ( # subshell to avoid pollution of calling environment
                insinto "${SITELISP}"
                doins "${T}/$(basename "${sf}")"
        )
}

# @FUNCTION: elisp-site-regen
# @DESCRIPTION:
# Regenerate site-gentoo.el file.

elisp-site-regen() {
        local sflist sf line

        einfon "Regenerating ${SITELISP}/site-gentoo.el ..."
        cat <<-EOF >"${T}"/site-gentoo.el
        ;;; site-gentoo.el --- site initialisation for Gentoo-installed packages

        ;;; Commentary:
        ;; Automatically generated by elisp-common.eclass
        ;; DO NOT EDIT THIS FILE

        ;;; Code:
        EOF

        for sf in "${ROOT}${SITELISP}"/[0-9][0-9]*-gentoo.el
        do
                [ -r "${sf}" ] || continue
                sflist="${sflist} $(basename "${sf}")"
                cat "${sf}" >>"${T}"/site-gentoo.el
        done

        cat <<-EOF >>"${T}"/site-gentoo.el

        (provide 'site-gentoo)

        ;; Local Variables:
        ;; no-byte-compile: t
        ;; End:
        ;;; site-gentoo.el ends here
        EOF

        if cmp -s "${ROOT}${SITELISP}"/site-gentoo.el "${T}"/site-gentoo.el; then
                # This prevents outputting unnecessary text when there
                # was actually no change
                # A case is a remerge where we have doubled output
                echo " no changes."
        else
                mv "${T}"/site-gentoo.el "${ROOT}${SITELISP}"/site-gentoo.el
                echo; einfo
                for sf in ${sflist}; do
                        einfo "  Adding ${sf} ..."
                done
                while read line; do einfo "${line}"; done <<EOF

All site initialisation for Gentoo-installed packages is added to
/usr/share/emacs/site-lisp/site-gentoo.el; site-start.el is no longer
managed by Gentoo. You are responsible for all maintenance of
site-start.el if there is such a file.

In order for this site initialisation to be loaded for all users
automatically, you can add a line like this:

        (load "/usr/share/emacs/site-lisp/site-gentoo" nil t)

to /usr/share/emacs/site-lisp/site-start.el.  Alternatively, that line
can be added by individual users to their initialisation files, or for
greater flexibility, users can select which of the package-specific
initialisation files in /usr/share/emacs/site-lisp/ to load.
EOF
                echo
        fi
}

# @FUNCTION: elisp-comp
# @USAGE: <list of elisp files>
# @DESCRIPTION:
# Byte-compile interdependent Emacs Lisp files.
#
# This function byte-compiles all ".el" files which are part of its
# arguments, using GNU Emacs, and puts the resulting ".elc" files into the
# current directory, so disregarding the original directories used in ".el"
# arguments.
#
# This function manages in such a way that all Emacs Lisp files to be
# compiled are made visible between themselves, in the event they require or
# load one another.

elisp-comp() {
        # Copyright 1995 Free Software Foundation, Inc.
        # François Pinard <pinard@iro.umontreal.ca>, 1995.
        # Originally taken from GNU autotools.

        test $# -gt 0 || return 1

        if test -z "${EMACS}" || test "${EMACS}" = "t"; then
                # Value of "t" means we are running in a shell under Emacs.
                # Just assume Emacs is called "emacs".
                EMACS=/usr/bin/emacs
        fi
        einfo "Compiling GNU Emacs Elisp files ..."

        tempdir=elc.$$
        mkdir ${tempdir}
        cp "$@" ${tempdir}
        pushd ${tempdir}

        echo "(add-to-list 'load-path \"../\")" > script
        ${EMACS_BATCH_CLEAN} -l script -f batch-byte-compile *.el
        local ret=$?
        mv *.elc ..

        popd
        rm -fr ${tempdir}
        return ${ret}
}
1	# Copyright 1999-2007 Gentoo Foundation
2	# Distributed under the terms of the GNU General Public License v2
3	# $Header: /var/cvsroot/gentoo-x86/eclass/elisp-common.eclass,v 1.27 2007/08/27 19:41:03 ulm Exp $
4	#
5	# Copyright 2007 Christian Faulhammer <opfer@gentoo.org>
6	# Copyright 2002-2004 Matthew Kennedy <mkennedy@gentoo.org>
7	# Copyright 2004-2005 Mamoru Komachi <usata@gentoo.org>
8	# Copyright 2003 Jeremy Maitin-Shepard <jbms@attbi.com>
9	# Copyright 2007 Ulrich Mueller <ulm@gentoo.org>
10	#
11	# @ECLASS: elisp-common.eclass
12	# @MAINTAINER:
13	# Feel free to contact the Emacs team through emacs@gentoo.org if you have
14	# problems, suggestions or questions.
15	# @BLURB: Emacs-related installation utilities
16	# @DESCRIPTION:
17	#
18	# Usually you want to use this eclass for (optional) GNU Emacs support of
19	# your package. This is NOT for XEmacs!
20	#
21	# Many of the steps here are sometimes done by the build system of your
22	# package (especially compilation), so this is mainly for standalone elisp
23	# files you gathered from somewhere else.
24	#
25	# When relying on the emacs USE flag, you need to add
26	#
27	# emacs? ( virtual/emacs )
28	#
29	# to your DEPEND/RDEPEND line and use the functions provided here to bring
30	# the files to the correct locations.
31	#
32	# .SS
33	# src_compile() usage:
34	#
35	# An elisp file is compiled by the elisp-compile() function defined here and
36	# simply takes the source files as arguments.
37	#
38	# elisp-compile *.el \|\| die "elisp-compile failed"
39	#
40	# In the case of interdependent elisp files, you can use the elisp-comp()
41	# function which makes sure all files are loadable.
42	#
43	# elisp-comp *.el \|\| die "elisp-comp failed"
44	#
45	# Function elisp-make-autoload-file() can be used to generate a file with
46	# autoload definitions for the lisp functions. It takes the output file name
47	# (default: "${PN}-autoloads.el") and a list of directories (default: working
48	# directory) as its arguments. Use of this function requires that the elisp
49	# source files contain magic ";;;###autoload" comments. See the Emacs Lisp
50	# Reference Manual (node "Autoload") for a detailed explanation.
51	#
52	# .SS
53	# src_install() usage:
54	#
55	# The resulting compiled files (.elc) should be put in a subdirectory of
56	# /usr/share/emacs/site-lisp/ which is named after the first argument
57	# of elisp-install(). The following parameters are the files to be put in
58	# that directory. Usually the subdirectory should be ${PN}, you can choose
59	# something else, but remember to tell elisp-site-file-install() (see below)
60	# the change, as it defaults to ${PN}.
61	#
62	# elisp-install ${PN} .el .elc \|\| die "elisp-install failed"
63	#
64	# To let the Emacs support be activated by Emacs on startup, you need
65	# to provide a site file (shipped in ${FILESDIR}) which contains the startup
66	# code (have a look in the documentation of your software). Normally this
67	# would look like this:
68	#
69	# ;;; csv-mode site-lisp configuration
70	#
71	# (add-to-list 'load-path "@SITELISP@")
72	# (add-to-list 'auto-mode-alist '("\\.csv\\'" . csv-mode))
73	# (autoload 'csv-mode "csv-mode" "Major mode for csv files." t)
74	#
75	# If your Emacs support files are installed in a subdirectory of
76	# /usr/share/emacs/site-lisp/ (which is recommended if more than one file is
77	# installed), you need to extend Emacs' load-path as shown in the first
78	# non-comment. The elisp-site-file-install() function of this eclass will
79	# replace "@SITELISP@" by the actual path.
80	#
81	# The next line tells Emacs to load the mode opening a file ending with
82	# ".csv" and load functions depending on the context and needed features.
83	# Be careful though. Commands as "load-library" or "require" bloat the
84	# editor as they are loaded on every startup. When having a lot of Emacs
85	# support files, users may be annoyed by the start-up time. Also avoid
86	# keybindings as they might interfere with the user's settings. Give a hint
87	# in pkg_postinst(), which should be enough.
88	#
89	# The naming scheme for this site file is "[0-9][0-9]*-gentoo.el", where the
90	# two digits at the beginning define the loading order. So if you depend on
91	# another Emacs package, your site file's number must be higher!
92	#
93	# Best practice is to define a SITEFILE variable in the global scope of your
94	# ebuild (right after DEPEND e.g.):
95	#
96	# SITEFILE=50${PN}-gentoo.el
97	#
98	# Which is then installed by
99	#
100	# elisp-site-file-install "${FILESDIR}/${SITEFILE}"
101	#
102	# in src_install(). If your subdirectory is not named ${PN}, give the
103	# differing name as second argument.
104	#
105	# .SS
106	# pkg_postinst() / pkg_postrm() usage:
107	#
108	# After that you need to recreate the start-up file of Emacs after emerging
109	# and unmerging by using
110	#
111	# pkg_postinst() {
112	# elisp-site-regen
113	# }
114	#
115	# pkg_postrm() {
116	# elisp-site-regen
117	# }
118	#
119	# When having optional Emacs support, you should prepend "use emacs &&" to
120	# above calls of elisp-site-regen(). Don't use "has_version virtual/emacs"!
121	# When unmerging the state of the emacs USE flag is taken from the package
122	# database and not from the environment, so it is no problem when you unset
123	# USE=emacs between merge and unmerge of a package.
124	#
125	# .SS
126	# Miscellaneous functions:
127	#
128	# elisp-emacs-version() outputs the version of the currently active Emacs.
129
130	SITELISP=/usr/share/emacs/site-lisp
131	SITEFILE=50${PN}-gentoo.el
132	EMACS=/usr/bin/emacs
133	# The following works for Emacs versions 18-23, don't change it.
134	EMACS_BATCH_CLEAN="${EMACS} -batch -q --no-site-file"
135
136	# @FUNCTION: elisp-compile
137	# @USAGE: <list of elisp files>
138	# @DESCRIPTION:
139	# Byte-compile Emacs Lisp files.
140
141	elisp-compile() {
142	einfo "Compiling GNU Emacs Elisp files ..."
143	${EMACS_BATCH_CLEAN} -f batch-byte-compile "$@"
144	}
145
146	# @FUNCTION: elisp-emacs-version
147	# @DESCRIPTION:
148	# Output version of currently active Emacs.
149
150	elisp-emacs-version() {
151	# The following will work for at least versions 18-23.
152	echo "(princ emacs-version)" >"${T}"/emacs-version.el
153	${EMACS_BATCH_CLEAN} -l "${T}"/emacs-version.el
154	}
155
156	# @FUNCTION: elisp-make-autoload-file
157	# @USAGE: [output file] [list of directories]
158	# @DESCRIPTION:
159	# Generate a file with autoload definitions for the lisp functions.
160
161	elisp-make-autoload-file () {
162	local f="${1:-${PN}-autoloads.el}"
163	shift
164	einfo "Generating autoload file for GNU Emacs ..."
165
166	sed 's/^FF/\f/' >"${f}" <<-EOF
167	;;; ${f##*/} --- autoloads for ${P}
168
169	;;; Commentary:
170	;; Automatically generated by elisp-common.eclass
171	;; DO NOT EDIT THIS FILE
172
173	;;; Code:
174	FF
175	;; Local Variables:
176	;; version-control: never
177	;; no-byte-compile: t
178	;; no-update-autoloads: t
179	;; End:
180	;;; ${f##*/} ends here
181	EOF
182
183	${EMACS_BATCH_CLEAN} \
184	--eval "(setq make-backup-files nil)" \
185	--eval "(setq generated-autoload-file (expand-file-name \"${f}\"))" \
186	-f batch-update-autoloads "${@-.}"
187	}
188
189	# @FUNCTION: elisp-install
190	# @USAGE: <subdirectory> <list of files>
191	# @DESCRIPTION:
192	# Install files in SITELISP directory.
193
194	elisp-install() {
195	local subdir="$1"
196	shift
197	einfo "Installing Elisp files for GNU Emacs support ..."
198	( # subshell to avoid pollution of calling environment
199	insinto "${SITELISP}/${subdir}"
200	doins "$@"
201	)
202	}
203
204	# @FUNCTION: elisp-site-file-install
205	# @USAGE: <site-init file> [subdirectory]
206	# @DESCRIPTION:
207	# Install Emacs site-init file in SITELISP directory.
208
209	elisp-site-file-install() {
210	local sf="$1" my_pn="${2:-${PN}}"
211	einfo "Installing site initialisation file for GNU Emacs ..."
212	cp "${sf}" "${T}"
213	sed -i "s:@SITELISP@:${SITELISP}/${my_pn}:g" "${T}/$(basename "${sf}")"
214	( # subshell to avoid pollution of calling environment
215	insinto "${SITELISP}"
216	doins "${T}/$(basename "${sf}")"
217	)
218	}
219
220	# @FUNCTION: elisp-site-regen
221	# @DESCRIPTION:
222	# Regenerate site-gentoo.el file.
223
224	elisp-site-regen() {
225	local sflist sf line
226
227	einfon "Regenerating ${SITELISP}/site-gentoo.el ..."
228	cat <<-EOF >"${T}"/site-gentoo.el
229	;;; site-gentoo.el --- site initialisation for Gentoo-installed packages
230
231	;;; Commentary:
232	;; Automatically generated by elisp-common.eclass
233	;; DO NOT EDIT THIS FILE
234
235	;;; Code:
236	EOF
237
238	for sf in "${ROOT}${SITELISP}"/[0-9][0-9]*-gentoo.el
239	do
240	[ -r "${sf}" ] \|\| continue
241	sflist="${sflist} $(basename "${sf}")"
242	cat "${sf}" >>"${T}"/site-gentoo.el
243	done
244
245	cat <<-EOF >>"${T}"/site-gentoo.el
246
247	(provide 'site-gentoo)
248
249	;; Local Variables:
250	;; no-byte-compile: t
251	;; End:
252	;;; site-gentoo.el ends here
253	EOF
254
255	if cmp -s "${ROOT}${SITELISP}"/site-gentoo.el "${T}"/site-gentoo.el; then
256	# This prevents outputting unnecessary text when there
257	# was actually no change
258	# A case is a remerge where we have doubled output
259	echo " no changes."
260	else
261	mv "${T}"/site-gentoo.el "${ROOT}${SITELISP}"/site-gentoo.el
262	echo; einfo
263	for sf in ${sflist}; do
264	einfo " Adding ${sf} ..."
265	done
266	while read line; do einfo "${line}"; done <<EOF
267
268	All site initialisation for Gentoo-installed packages is added to
269	/usr/share/emacs/site-lisp/site-gentoo.el; site-start.el is no longer
270	managed by Gentoo. You are responsible for all maintenance of
271	site-start.el if there is such a file.
272
273	In order for this site initialisation to be loaded for all users
274	automatically, you can add a line like this:
275
276	(load "/usr/share/emacs/site-lisp/site-gentoo" nil t)
277
278	to /usr/share/emacs/site-lisp/site-start.el. Alternatively, that line
279	can be added by individual users to their initialisation files, or for
280	greater flexibility, users can select which of the package-specific
281	initialisation files in /usr/share/emacs/site-lisp/ to load.
282	EOF
283	echo
284	fi
285	}
286
287	# @FUNCTION: elisp-comp
288	# @USAGE: <list of elisp files>
289	# @DESCRIPTION:
290	# Byte-compile interdependent Emacs Lisp files.
291	#
292	# This function byte-compiles all ".el" files which are part of its
293	# arguments, using GNU Emacs, and puts the resulting ".elc" files into the
294	# current directory, so disregarding the original directories used in ".el"
295	# arguments.
296	#
297	# This function manages in such a way that all Emacs Lisp files to be
298	# compiled are made visible between themselves, in the event they require or
299	# load one another.
300
301	elisp-comp() {
302	# Copyright 1995 Free Software Foundation, Inc.
303	# François Pinard <pinard@iro.umontreal.ca>, 1995.
304	# Originally taken from GNU autotools.
305
306	test $# -gt 0 \|\| return 1
307
308	if test -z "${EMACS}" \|\| test "${EMACS}" = "t"; then
309	# Value of "t" means we are running in a shell under Emacs.
310	# Just assume Emacs is called "emacs".
311	EMACS=/usr/bin/emacs
312	fi
313	einfo "Compiling GNU Emacs Elisp files ..."
314
315	tempdir=elc.$$
316	mkdir ${tempdir}
317	cp "$@" ${tempdir}
318	pushd ${tempdir}
319
320	echo "(add-to-list 'load-path \"../\")" > script
321	${EMACS_BATCH_CLEAN} -l script -f batch-byte-compile *.el
322	local ret=$?
323	mv *.elc ..
324
325	popd
326	rm -fr ${tempdir}
327	return ${ret}
328	}