44.3 多文件软件包

多文件软件包的创建不如单文件软件包便捷,但功能更为丰富:可以包含多个 Emacs Lisp 文件、一份 Info 手册以及其他类型文件(例如图片)。

在安装之前,多文件软件包以 tar 文件形式存放在软件包归档中。该 tar 文件必须命名为 name-version.tar,其中 name 为软件包名称,version 为版本号。文件解压后,所有内容必须位于名为 name-version 的目录下,即该软件包的 内容目录(content directory)(see 软件包基础)。文件也可以解压到内容目录的子目录中。

内容目录中必须有一个文件名为 name-pkg.el。该文件只能包含一个 Lisp 表达式,即对下文所述 define-package 函数的调用。它用于定义软件包的属性:版本、简要描述与依赖项。

例如,若将 superfrobnicator 的 1.3 版以多文件软件包形式发布,对应的 tar 文件应为 superfrobnicator-1.3.tar。其内容解压后位于 superfrobnicator-1.3 目录下,其中包含文件 superfrobnicator-pkg.el

Function: define-package name version &optional docstring requirements

该函数用于定义一个软件包。name 为软件包名称,是一个字符串。version 为版本号,字符串格式需能被 version-to-list 函数识别。docstring 为简要描述。

requirements 是依赖软件包及其版本的列表。列表中每个元素格式为 (dep-name dep-version),其中 dep-name 是一个符号,其名称为依赖软件包名,dep-version 为该依赖的版本(字符串)。特殊值 ‘emacs’ 表示该软件包依赖指定版本的 Emacs。

若内容目录中包含名为 README 的文件,该文件将作为详细描述(会覆盖任何 ‘;;; Commentary:’ 段落)。

若内容目录中包含名为 dir 的文件,会被视为由 install-info 生成的 Info 目录文件。See Invoking install-info in Texinfo. 对应的相关 Info 文件也应存放在内容目录中。这种情况下,Emacs 在启用该软件包时会自动将内容目录加入 Info-directory-list

软件包中不要包含任何 .elc 文件。这类文件会在软件包安装时自动生成。注意,无法控制文件字节编译的先后顺序。

不要包含任何名为 name-autoloads.el 的文件。该文件为软件包自动加载定义保留(see 软件包基础),会在安装软件包时,通过扫描包内所有 Lisp 文件中的自动加载魔法注释自动生成。

若多文件软件包包含辅助数据文件(如图片),软件包的 Lisp 代码可通过变量 load-file-name 引用这些文件(see 加载)。示例如下:

(defconst superfrobnicator-base (file-name-directory load-file-name))

(defun superfrobnicator-fetch-image (file)
  (expand-file-name file superfrobnicator-base))

若软件包中包含不希望分发给用户的文件(例如回归测试文件),可将其加入 .elpaignore 文件。该文件中每行列出一个文件或匹配文件的通配符;在 ELPA 上生成软件包 tar 包时会忽略这些文件(see 创建与维护软件包归档)。(ELPA 在准备供下载的软件包时,会通过 -X 命令行选项将该文件传递给 tar 命令。)