ELISP-COMMON.ECLASS

部分：eclass-manpages (5)
更新时间：2024 年 11 月
索引返回主目录

名称

elisp-common.eclass - Emacs 相关安装工具

描述

通常，您希望将此 eclass 用于软件包的 (可选) GNU Emacs 支持。这不是为 XEmacs 设计的！

这里的许多步骤有时由软件包的构建系统（特别是编译）完成，因此这主要用于您从其他地方收集的独立 elisp 文件。

当依赖 emacs USE 标志时，您需要添加

        emacs? ( >=app-editors/emacs-25.3:* )

到您的 DEPEND/RDEPEND 行并使用此处提供的函数将文件带到正确的位置。

如果您的软件包需要最低 Emacs 版本，例如 Emacs 26.1，那么依赖项应该是在 >=app-editors/emacs-26.1:* 而不是。因为用户可以使用 eselect 选择 Emacs 可执行文件，所以您还应该确保活动 Emacs 版本足够。如果您使用 Emacs 版本分配变量 NEED_EMACS，eclass 将自动确保这一点，例如

        NEED_EMACS=26.1

请注意，这应该只针对已知在较低 Emacs 版本上会失败的软件包。

src_compile() 用法

elisp 文件由此处定义的 elisp-compile() 函数编译，并且只接受源文件作为参数。相互依赖的 elisp 文件的情况也得到支持，因为当前目录被添加到加载路径中，这确保所有文件都是可加载的。

        elisp-compile *.el

函数 elisp-make-autoload-file() 可用于生成包含 lisp 函数自动加载定义的文件。它接受输出文件名（默认值："${PN}-autoloads.el") 和目录列表（默认值：工作目录）作为参数。使用此函数要求 elisp 源文件包含魔术 ";;;###autoload" 注释。有关详细说明，请参见 Emacs Lisp 参考手册（节点“自动加载”）。

src_install() 用法

生成的编译文件 (.elc) 应该放在 /usr/share/emacs/site-lisp/ 的子目录中，该子目录以 elisp-install() 的第一个参数命名。以下参数是要放在该目录中的文件。通常子目录应该是 ${PN}，您可以选择其他名称，但请记住将 elisp-site-file-install()（见下文）告知更改，因为它默认为 ${PN}。

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

要让 Emacs 支持在 Emacs 启动时被激活，您需要提供一个站点文件（位于 ${FILESDIR} 中），其中包含启动代码（查看软件文档）。通常是这样的

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

如果您的 Emacs 支持文件安装在 /usr/share/emacs/site-lisp/ 的子目录中（强烈建议这样做），您需要扩展 Emacs 的加载路径，如第一行非注释行所示。此 eclass 的 elisp-site-file-install() 函数将用实际路径替换 "@SITELISP@" 和 "@SITEETC@"。

下一行告诉 Emacs 加载以 ".csv" 结尾的文件打开模式并根据上下文和所需功能加载函数。但要小心。诸如“load-library”或“require”之类的命令会使编辑器膨胀，因为它们在每次启动时都会加载。当拥有许多 Emacs 支持文件时，用户可能会因启动时间而感到厌烦。还要避免键绑定，因为它们可能会干扰用户的设置。在 pkg_postinst() 中给出提示就足够了。指导原则是在使用您的软件包时，不要自行更改标准 Emacs 行为。

此站点初始化文件的命名方案与 shell 模式 "[1-8][0-9]*-gentoo*.el" 相匹配，其中开头的两位数字定义了加载顺序（低于 10 或高于 89 的数字保留供内部使用）。因此，如果您的初始化依赖于另一个 Emacs 软件包，那么您的站点文件的数字必须更高！如果没有这样的相互依赖关系，那么数字应该为 50。否则，优先考虑可被 10 整除的数字。

最佳做法是在 ebuild 的全局范围内（例如，在 S 或 RDEPEND 之后）定义 SITEFILE 变量

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

然后在 src_install() 中通过

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

进行安装。"-gentoo" 部分之后的任何字符以及扩展名之前的任何字符都将从目标文件的名称中删除。例如，文件 "50${PN}-gentoo-${PV}.el" 将被安装为 "50${PN}-gentoo.el"。如果您的子目录不是名为 ${PN}，请将不同的名称作为第二个参数给出。

对于只将软件包的子目录添加到加载路径的简单情况，函数 elisp-make-site-file() 将创建并安装一个站点初始化文件，该文件只执行此操作

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

同样，这必须在 src_install() 中调用。有关其使用方式的更多详细信息，请参见函数文档。

pkg_setup() 用法

如果您的 ebuild 使用 elisp-compile eclass 函数编译其 elisp 文件（见上文），那么您不需要 pkg_setup 阶段，因为 elisp-compile 和 elisp-make-autoload-file 会执行自己的健全性检查。另一方面，如果 elisp 文件由软件包的构建系统编译，那么通常不会检查 Emacs 版本。在这种情况下，您可以在 pkg_setup 中添加显式检查

        elisp-check-emacs-version

当拥有可选的 Emacs 支持时，您应该在 elisp-check-emacs-version() 的上述调用之前添加 "use emacs &&"。

pkg_postinst() / pkg_postrm() 用法

之后，您需要在使用后重新创建 Emacs 的启动文件

        pkg_postinst() {
                elisp-site-regen
        }

        pkg_postrm() {
                elisp-site-regen
        }

同样，对于可选的 Emacs 支持，您应该在 elisp-site-regen() 的上述调用之前添加 "use emacs &&"。

支持的 EAPIS

7 8

函数

elisp-emacs-version

输出当前活动 Emacs 的版本。

返回值：Emacs 的退出状态

elisp-check-emacs-version [version]

测试 eselected Emacs 版本是否至少为 NEED_EMACS 变量中指定的 GNU Emacs 版本，否则退出。

elisp-compile <elisp 文件列表>

字节编译 Emacs Lisp 文件。

此函数使用 GNU Emacs 来字节编译其参数指定的 ".el" 文件。生成的字节码 (".elc") 文件将放置在与其对应源文件相同的目录中。

当前目录被添加到加载路径中。这将确保相互依赖的 Emacs Lisp 文件彼此可见，以防它们相互需要或加载。

elisp-make-autoload-file [输出文件] [目录列表]

为 lisp 函数生成一个包含自动加载定义的文件。

elisp-org-export-to <导出文件类型> <Org 文件路径>

使用 Emacs Org 的 "export-to" 函数将给定的 Org 文件转换为选定的格式。

示例

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

elisp-test-buttercup [测试子目录] [测试运行器选项] ...

使用 "buttercup" 测试运行器运行 ELisp 软件包测试。

选项 "测试子目录" 可以给出任意次数，应该像传递给 Emacs 或测试工具一样给出，而不是作为字符串给出。

选项 "测试子目录" 和 "测试运行器选项" 是可选的，但如果需要提供 "测试运行器选项"，则也必须指定 "测试子目录"。

elisp-test-ert-runner [测试子目录] [测试运行器选项] ...

使用 "ert-runner" 测试运行器运行 ELisp 软件包测试。

选项 "测试子目录" 可以给出任意次数，应该像传递给 Emacs 或测试工具一样给出，而不是作为字符串给出。

选项 "测试子目录" 和 "测试运行器选项" 是可选的，但如果需要提供 "测试运行器选项"，则也必须指定 "测试子目录"。

elisp-test-ert [测试子目录] [测试运行器选项] ...

使用 "ert"（Emacs 的内置测试运行器）运行 ELisp 软件包测试。

选项 "测试子目录" 可以给出任意次数，应该像传递给 Emacs 或测试工具一样给出，而不是作为字符串给出。

选项 "测试子目录" 和 "测试运行器选项" 是可选的，但如果需要提供 "测试运行器选项"，则也必须指定 "测试子目录"。

elisp-enable-tests [--optional] <测试运行器> [测试运行器选项] ...

为使用指定的测试运行器运行测试设置 IUSE、RESTRICT、BDEPEND 和测试运行器函数。

测试运行器参数必须是以下之一

- buttercup: 对于 "buttercup"（通过 "app-emacs/buttercup" 提供）

- ert-runner: 对于 "ert-runner"（通过 "app-emacs/ert-runner" 提供）

- ert: 对于内置的 GNU Emacs 测试工具

如果传递 "--optional" 标志（在指定测试运行器之前），那么它将假定 ELisp 软件包是某个可选地启用 GNU Emacs 支持的项目的组成部分。这将正确设置测试和 Emacs 依赖项。

注意，传递给 "测试运行器" 的第一个选项是目录，其余的是适用于该给定运行器的其他选项。

此函数必须在继承之后调用，特别是在分配 "IUSE"、"RESTRICT" 和 "BDEPEND" 变量之后。建议在重新定义给定 ebuild 的阶段之前放置此调用。

示例

        inherit elisp-common

        ...

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

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

elisp-test

使用 ELisp 测试运行器测试软件包。

如果在事先执行 "elisp-enable-tests" 之前调用，则不执行任何操作，否则将使用给定的 "测试运行器选项" 调用测试运行器。

elisp-install <子目录> <文件列表>

在 SITELISP 目录中安装文件。

elisp-modules-install <子目录> <文件列表>

在 EMACSMODULES 目录中安装动态模块。

elisp-site-file-install <站点初始化文件> [子目录]

在 SITELISP 目录中安装 Emacs 站点初始化文件。自动插入一个包含软件包名称的标准注释头（除非它已存在）。标记 @SITELISP@、@SITEETC@ 和 @EMACSMODULES@ 分别被替换为软件包在 SITELISP、SITEETC 和 EMACSMODULES 中的子目录路径。

elisp-make-site-file <文件名> [子目录] [行]...

为软件包创建并安装一个站点初始化文件。默认情况下，这将将软件包的 SITELISP 子目录添加到 Emacs 的加载路径中

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

附加参数将作为行追加到目标文件。这些参数中的任何 @SITELISP@、@SITEETC@ 和 @EMACSMODULES@ 标记都将被替换，如 elisp-site-file-install 所述。

elisp-site-regen

根据 /usr/share/emacs/site-lisp/site-gentoo.d/ 目录中包的站点初始化文件，重新生成 site-gentoo.el 文件。

ECLASS 变量

SITELISP = /usr/share/emacs/site-lisp: 包安装 Emacs Lisp 文件的目录。
SITEETC = /usr/share/emacs/etc: 包安装其他（非 Lisp）文件的目录。
EMACSMODULES = /usr/@libdir@/emacs/modules: 包安装动态加载模块的目录。可能包含一个 @libdir@ 标记，该标记将被 $(get_libdir) 替换。
EMACS = ${EPREFIX}/usr/bin/emacs: Emacs 可执行文件的路径。
EMACSFLAGS = "-batch -q --no-site-file": 以批处理模式执行 Emacs 的标志。这些适用于 Emacs 版本 18-24，所以不要更改它们。
BYTECOMPFLAGS = "-L .": 在 elisp-compile() 中用于字节编译的 Emacs 标志。
NEED_EMACS ?= 25.3: 包所需的最小 Emacs 版本。