diff options
Diffstat (limited to 'devdocs/elisp/multi_002dfile-packages.html')
| -rw-r--r-- | devdocs/elisp/multi_002dfile-packages.html | 16 |
1 files changed, 16 insertions, 0 deletions
diff --git a/devdocs/elisp/multi_002dfile-packages.html b/devdocs/elisp/multi_002dfile-packages.html new file mode 100644 index 00000000..a8ead783 --- /dev/null +++ b/devdocs/elisp/multi_002dfile-packages.html @@ -0,0 +1,16 @@ + <h3 class="section">Multi-file Packages</h3> <p>A multi-file package is less convenient to create than a single-file package, but it offers more features: it can include multiple Emacs Lisp files, an Info manual, and other file types (such as images). </p> <p>Prior to installation, a multi-file package is stored in a package archive as a tar file. The tar file must be named <samp><var>name</var>-<var>version</var>.tar</samp>, where <var>name</var> is the package name and <var>version</var> is the version number. Its contents, once extracted, must all appear in a directory named <samp><var>name</var>-<var>version</var></samp>, the <em>content directory</em> (see <a href="packaging-basics">Packaging Basics</a>). Files may also extract into subdirectories of the content directory. </p> <p>One of the files in the content directory must be named <samp><var>name</var>-pkg.el</samp>. It must contain a single Lisp form, consisting of a call to the function <code>define-package</code>, described below. This defines the package’s attributes: version, brief description, and requirements. </p> <p>For example, if we distribute version 1.3 of the superfrobnicator as a multi-file package, the tar file would be <samp>superfrobnicator-1.3.tar</samp>. Its contents would extract into the directory <samp>superfrobnicator-1.3</samp>, and one of these would be the file <samp>superfrobnicator-pkg.el</samp>. </p> <dl> <dt id="define-package">Function: <strong>define-package</strong> <em>name version &optional docstring requirements</em> +</dt> <dd> +<p>This function defines a package. <var>name</var> is the package name, a string. <var>version</var> is the version, as a string of a form that can be understood by the function <code>version-to-list</code>. <var>docstring</var> is the brief description. </p> <p><var>requirements</var> is a list of required packages and their versions. Each element in this list should have the form <code>(<var>dep-name</var> +<var>dep-version</var>)</code>, where <var>dep-name</var> is a symbol whose name is the dependency’s package name, and <var>dep-version</var> is the dependency’s version (a string). </p> +</dd> +</dl> <p>If the content directory contains a file named <samp>README</samp>, this file is used as the long description (overriding any ‘<samp>;;; Commentary:</samp>’ section). </p> <p>If the content directory contains a file named <samp>dir</samp>, this is assumed to be an Info directory file made with <code>install-info</code>. See <a href="https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-install_002dinfo.html#Invoking-install_002dinfo">Invoking install-info</a> in <cite>Texinfo</cite>. The relevant Info files should also be present in the content directory. In this case, Emacs will automatically add the content directory to <code>Info-directory-list</code> when the package is activated. </p> <p>Do not include any <samp>.elc</samp> files in the package. Those are created when the package is installed. Note that there is no way to control the order in which files are byte-compiled. </p> <p>Do not include any file named <samp><var>name</var>-autoloads.el</samp>. This file is reserved for the package’s autoload definitions (see <a href="packaging-basics">Packaging Basics</a>). It is created automatically when the package is installed, by searching all the Lisp files in the package for autoload magic comments. </p> <p>If the multi-file package contains auxiliary data files (such as images), the package’s Lisp code can refer to these files via the variable <code>load-file-name</code> (see <a href="loading">Loading</a>). Here is an example: </p> <div class="example"> <pre class="example">(defconst superfrobnicator-base (file-name-directory load-file-name)) + +(defun superfrobnicator-fetch-image (file) + (expand-file-name file superfrobnicator-base)) +</pre> +</div><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Multi_002dfile-Packages.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Multi_002dfile-Packages.html</a> + </p> +</div> |