"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/lispref/package.texi" (23 Apr 2018, 16578 Bytes) of package /linux/misc/emacs-26.1.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "package.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Preparing Lisp code for distribution

Emacs provides a standard way to distribute Emacs Lisp code to users. A package is a collection of one or more files, formatted and bundled in such a way that users can easily download, install, uninstall, and upgrade it.

The following sections describe how to create a package, and how to put it in a package archive for others to download. See Packages in The GNU Emacs Manual, for a description of user-level features of the packaging system.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Packaging Basics

A package is either a simple package or a multi-file package. A simple package is stored in a package archive as a single Emacs Lisp file, while a multi-file package is stored as a tar file (containing multiple Lisp files, and possibly non-Lisp files such as a manual).

In ordinary usage, the difference between simple packages and multi-file packages is relatively unimportant; the Package Menu interface makes no distinction between them. However, the procedure for creating them differs, as explained in the following sections.

Each package (whether simple or multi-file) has certain attributes:

Name

A short word (e.g., ‘auctex’). This is usually also the symbol prefix used in the program (@pxref{Coding Conventions}).

Version

A version number, in a form that the function version-to-list understands (e.g., ‘11.86’). Each release of a package should be accompanied by an increase in the version number so that it will be recognized as an upgrade by users querying the package archive.

Brief description

This is shown when the package is listed in the Package Menu. It should occupy a single line, ideally in 36 characters or less.

Long description

This is shown in the buffer created by C-h P (describe-package), following the package’s brief description and installation status. It normally spans multiple lines, and should fully describe the package’s capabilities and how to begin using it once it is installed.

Dependencies

A list of other packages (possibly including minimal acceptable version numbers) on which this package depends. The list may be empty, meaning this package has no dependencies. Otherwise, installing this package also automatically installs its dependencies, recursively; if any dependency cannot be found, the package cannot be installed.

Installing a package, either via the command package-install-file, or via the Package Menu, creates a subdirectory of package-user-dir named ‘name-version’, where name is the package’s name and version its version (e.g., ‘~/.emacs.d/elpa/auctex-11.86/’). We call this the package’s content directory. It is where Emacs puts the package’s contents (the single Lisp file for a simple package, or the files extracted from a multi-file package).

Emacs then searches every Lisp file in the content directory for autoload magic comments (@pxref{Autoload}). These autoload definitions are saved to a file named ‘name-autoloads.el’ in the content directory. They are typically used to autoload the principal user commands defined in the package, but they can also perform other tasks, such as adding an element to auto-mode-alist (@pxref{Auto Major Mode}). Note that a package typically does not autoload every function and variable defined within it—only the handful of commands typically called to begin using the package. Emacs then byte-compiles every Lisp file in the package.

After installation, the installed package is loaded: Emacs adds the package’s content directory to load-path, and evaluates the autoload definitions in ‘name-autoloads.el’.

Whenever Emacs starts up, it automatically calls the function package-initialize to load installed packages. This is done after loading the init file and abbrev file (if any) and before running after-init-hook (@pxref{Startup Summary}). Automatic package loading is disabled if the user option package-enable-at-startup is nil.

Command: package-initialize &optional no-activate

This function initializes Emacs’ internal record of which packages are installed, and loads them. The user option package-load-list specifies which packages to load; by default, all installed packages are loaded. If called during startup, this function also sets package-enable-at-startup to nil, to avoid accidentally loading the packages twice. See Package Installation in The GNU Emacs Manual.

The optional argument no-activate, if non-nil, causes Emacs to update its record of installed packages without actually loading them; it is for internal use only.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Simple Packages

A simple package consists of a single Emacs Lisp source file. The file must conform to the Emacs Lisp library header conventions (@pxref{Library Headers}). The package’s attributes are taken from the various headers, as illustrated by the following example:

;;; superfrobnicator.el --- Frobnicate and bifurcate flanges

;; Copyright (C) 2011 Free Software Foundation, Inc.
;; Author: J. R. Hacker <jrh@example.com>
;; Version: 1.3
;; Package-Requires: ((flange "1.0"))
;; Keywords: multimedia, frobnicate
;; URL: http://example.com/jrhacker/superfrobnicate

…

;;; Commentary:

;; This package provides a minor mode to frobnicate and/or
;; bifurcate any flanges you desire.  To activate it, just type
…

;;;###autoload
(define-minor-mode superfrobnicator-mode
…

The name of the package is the same as the base name of the file, as written on the first line. Here, it is ‘superfrobnicator’.

The brief description is also taken from the first line. Here, it is ‘Frobnicate and bifurcate flanges’.

The version number comes from the ‘Package-Version’ header, if it exists, or from the ‘Version’ header otherwise. One or the other must be present. Here, the version number is 1.3.

If the file has a ‘;;; Commentary:’ section, this section is used as the long description. (When displaying the description, Emacs omits the ‘;;; Commentary:’ line, as well as the leading comment characters in the commentary itself.)

If the file has a ‘Package-Requires’ header, that is used as the package dependencies. In the above example, the package depends on the ‘flange’ package, version 1.0 or higher. @xref{Library Headers}, for a description of the ‘Package-Requires’ header. If the header is omitted, the package has no dependencies.

The ‘Keywords’ and ‘URL’ headers are optional, but recommended. The command describe-package uses these to add links to its output. The ‘Keywords’ header should contain at least one standard keyword from the finder-known-keywords list.

The file ought to also contain one or more autoload magic comments, as explained in Packaging Basics. In the above example, a magic comment autoloads superfrobnicator-mode.

See section Creating and Maintaining Package Archives, for an explanation of how to add a single-file package to a package archive.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Multi-file Packages

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

Prior to installation, a multi-file package is stored in a package archive as a tar file. The tar file must be named ‘name-version.tar’, where name is the package name and version is the version number. Its contents, once extracted, must all appear in a directory named ‘name-version’, the content directory (see section Packaging Basics). Files may also extract into subdirectories of the content directory.

One of the files in the content directory must be named ‘name-pkg.el’. It must contain a single Lisp form, consisting of a call to the function define-package, described below. This defines the package’s attributes: version, brief description, and requirements.

For example, if we distribute version 1.3 of the superfrobnicator as a multi-file package, the tar file would be ‘superfrobnicator-1.3.tar’. Its contents would extract into the directory ‘superfrobnicator-1.3’, and one of these would be the file ‘superfrobnicator-pkg.el’.

Function: define-package name version &optional docstring requirements

This function defines a package. name is the package name, a string. version is the version, as a string of a form that can be understood by the function version-to-list. docstring is the brief description.

requirements is a list of required packages and their versions. Each element in this list should have the form (dep-name dep-version), where dep-name is a symbol whose name is the dependency’s package name, and dep-version is the dependency’s version (a string).

If the content directory contains a file named ‘README’, this file is used as the long description.

If the content directory contains a file named ‘dir’, this is assumed to be an Info directory file made with install-info. See Invoking install-info in Texinfo. The relevant Info files should also be present in the content directory. In this case, Emacs will automatically add the content directory to Info-directory-list when the package is activated.

Do not include any ‘.elc’ 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.

Do not include any file named ‘name-autoloads.el’. This file is reserved for the package’s autoload definitions (see section Packaging Basics). It is created automatically when the package is installed, by searching all the Lisp files in the package for autoload magic comments.

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 load-file-name (@pxref{Loading}). Here is an example:

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Creating and Maintaining Package Archives

Via the Package Menu, users may download packages from package archives. Such archives are specified by the variable package-archives, whose default value contains a single entry: the archive hosted by the GNU project at https://elpa.gnu.org. This section describes how to set up and maintain a package archive.

User Option: package-archives

The value of this variable is an alist of package archives recognized by the Emacs package manager.

Each alist element corresponds to one archive, and should have the form (id . location), where id is the name of the archive (a string) and location is its base location (a string).

If the base location starts with ‘http:’ or ‘https:’, it is treated as an HTTP(S) URL, and packages are downloaded from this archive via HTTP(S) (as is the case for the default GNU archive).

Otherwise, the base location should be a directory name. In this case, Emacs retrieves packages from this archive via ordinary file access. Such local archives are mainly useful for testing.

A package archive is simply a directory in which the package files, and associated files, are stored. If you want the archive to be reachable via HTTP, this directory must be accessible to a web server. How to accomplish this is beyond the scope of this manual.

A convenient way to set up and update a package archive is via the package-x library. This is included with Emacs, but not loaded by default; type M-x load-library <RET> package-x <RET> to load it, or add (require 'package-x) to your init file. See Lisp Libraries in The GNU Emacs Manual. Once loaded, you can make use of the following:

User Option: package-archive-upload-base

The value of this variable is the base location of a package archive, as a directory name. The commands in the package-x library will use this base location.

The directory name should be absolute. You may specify a remote name, such as ‘/ssh:foo@example.com:/var/www/packages/’, if the package archive is on a different machine. See Remote Files in The GNU Emacs Manual.

Command: package-upload-file filename

This command prompts for filename, a file name, and uploads that file to package-archive-upload-base. The file must be either a simple package (a ‘.el’ file) or a multi-file package (a ‘.tar’ file); otherwise, an error is raised. The package attributes are automatically extracted, and the archive’s contents list is updated with this information.

If package-archive-upload-base does not specify a valid directory, the function prompts interactively for one. If the directory does not exist, it is created. The directory need not have any initial contents (i.e., you can use this command to populate an initially empty archive).

Command: package-upload-buffer

This command is similar to package-upload-file, but instead of prompting for a package file, it uploads the contents of the current buffer. The current buffer must be visiting a simple package (a ‘.el’ file) or a multi-file package (a ‘.tar’ file); otherwise, an error is raised.

After you create an archive, remember that it is not accessible in the Package Menu interface unless it is in package-archives.

Maintaining a public package archive entails a degree of responsibility. When Emacs users install packages from your archive, those packages can cause Emacs to run arbitrary code with the permissions of the installing user. (This is true for Emacs code in general, not just for packages.) So you should ensure that your archive is well-maintained and keep the hosting system secure.

One way to increase the security of your packages is to sign them using a cryptographic key. If you have generated a private/public gpg key pair, you can use gpg to sign the package like this:

gpg -ba -o file.sig file

For a single-file package, file is the package Lisp file; for a multi-file package, it is the package tar file. You can also sign the archive’s contents file in the same way. Make the ‘.sig’ files available in the same location as the packages. You should also make your public key available for people to download; e.g., by uploading it to a key server such as http://pgp.mit.edu/. When people install packages from your archive, they can use your public key to verify the signatures.

A full explanation of these matters is outside the scope of this manual. For more information on cryptographic keys and signing, see GnuPG in The GNU Privacy Guard Manual. Emacs comes with an interface to GNU Privacy Guard, see EasyPG in Emacs EasyPG Assistant Manual.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on June 2, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on June 2, 2018 using texi2html.