@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 2010-2012 Free Software Foundation, Inc.
+@c Copyright (C) 2010-2015 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Packaging, Antinews, System Interface, Top
+@node Packaging
@chapter Preparing Lisp code for distribution
@cindex package
@cindex Lisp package
@table @asis
@item Name
-A short word (e.g. @samp{auctex}). This is usually also the symbol
+A short word (e.g., @samp{auctex}). This is usually also the symbol
prefix used in the program (@pxref{Coding Conventions}).
@item Version
A version number, in a form that the function @code{version-to-list}
-understands (e.g. @samp{11.86}). Each release of a package should be
+understands (e.g., @samp{11.86}). Each release of a package should be
accompanied by an increase in the version number.
@item Brief description
or via the Package Menu, creates a subdirectory of
@code{package-user-dir} named @file{@var{name}-@var{version}}, where
@var{name} is the package's name and @var{version} its version
-(e.g. @file{~/.emacs.d/elpa/auctex-11.86/}). We call this the
+(e.g., @file{~/.emacs.d/elpa/auctex-11.86/}). We call this the
package's @dfn{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).
This function initializes Emacs' internal record of which packages are
installed, and loads them. The user option @code{package-load-list}
specifies which packages to load; by default, all installed packages
-are loaded. @xref{Package Installation,,, emacs, The GNU Emacs
-Manual}.
+are loaded. If called during startup, this function also sets
+@code{package-enable-at-startup} to @code{nil}, to avoid accidentally
+loading the packages twice. @xref{Package Installation,,, emacs, The
+GNU Emacs Manual}.
The optional argument @var{no-activate}, if non-@code{nil}, causes
Emacs to update its record of installed packages without actually
;; Author: J. R. Hacker <jrh@@example.com>
;; Version: 1.3
;; Package-Requires: ((flange "1.0"))
-;; Keywords: frobnicate
+;; Keywords: multimedia, frobnicate
+;; URL: http://example.com/jrhacker/superfrobnicate
@dots{}
Headers}, for a description of the @samp{Package-Requires} header. If
the header is omitted, the package has no dependencies.
+ The @samp{Keywords} and @samp{URL} headers are optional, but recommended.
+The command @code{describe-package} uses these to add links to its
+output. The @samp{Keywords} header should contain at least one
+standard keyword from the @code{finder-known-keywords} list.
+
The file ought to also contain one or more autoload magic comments,
as explained in @ref{Packaging Basics}. In the above example, a magic
comment autoloads @code{superfrobnicator-mode}.
Via the Package Menu, users may download packages from @dfn{package
archives}. Such archives are specified by the variable
@code{package-archives}, whose default value contains a single entry:
-the archive hosted by the GNU project at @url{elpa.gnu.org}. This
+the archive hosted by the GNU project at @url{http://elpa.gnu.org}. This
section describes how to set up and maintain a package archive.
@cindex base location, package 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.
+access. Such local archives are mainly useful for testing.
@end defopt
A package archive is simply a directory in which the package files,
A convenient way to set up and update a package archive is via the
@code{package-x} library. This is included with Emacs, but not loaded
-by default; type @kbd{M-x load-library @kbd{RET} package-x @kbd{RET}}
-to load it, or add @code{(require 'package-x)} to your init file.
+by default; type @kbd{M-x load-library @key{RET} package-x @key{RET}} to
+load it, or add @code{(require 'package-x)} to your init file.
@xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}.
Once loaded, you can make use of the following:
@noindent
After you create an archive, remember that it is not accessible in the
Package Menu interface unless it is in @code{package-archives}.
+
+@cindex package archive security
+@cindex package signing
+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 @dfn{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:
+
+@c FIXME EasyPG / package-x way to do this.
+@example
+gpg -ba -o @var{file}.sig @var{file}
+@end example
+
+@noindent
+For a single-file package, @var{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 @file{.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 @url{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,
+@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes
+with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa,
+Emacs EasyPG Assistant Manual}.