@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.
-@setfilename ../../info/package
-@node Packaging, Antinews, System Interface, Top
+@node Packaging
@chapter Preparing Lisp code for distribution
@cindex package
@cindex Lisp package
The following sections describe how to create a package, and how to
put it in a @dfn{package archive} for others to download.
+@xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of
+user-level features of the packaging system.
@menu
* Packaging Basics:: The basic concepts of Emacs Lisp packages.
@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
@end table
@cindex content directory, package
- Installing a package, either via the Package Menu, or via the
-command @code{package-install-file}, creates a subdirectory of
+ Installing a package, either via the command @code{package-install-file},
+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).
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
-@code{auto-mode-alist} (@pxref{Auto Major Mode}). During this time,
-Emacs will also byte-compile the Lisp files.
-
- After installation, and (by default) each time Emacs is started, the
-installed package is @dfn{activated}. During activation, Emacs adds
-the package's content directory to @code{load-path}, and evaluates the
-autoload definitions in @file{@var{name}-autoloads.el}.
-
- Note that a package typically does @emph{not} autoload every
-function and variable defined within it---only the handful of commands
-typically called to begin using the package.
+@code{auto-mode-alist} (@pxref{Auto Major Mode}). Note that a package
+typically does @emph{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 @dfn{loaded}: Emacs
+adds the package's content directory to @code{load-path}, and
+evaluates the autoload definitions in @file{@var{name}-autoloads.el}.
+
+ Whenever Emacs starts up, it automatically calls the function
+@code{package-initialize} to load installed packages. This is done
+after loading the init file and abbrev file (if any) and before
+running @code{after-init-hook} (@pxref{Startup Summary}). Automatic
+package loading is disabled if the user option
+@code{package-enable-at-startup} is @code{nil}.
+
+@deffn Command package-initialize &optional no-activate
+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. 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
+loading them; it is for internal use only.
+@end deffn
@node Simple Packages
@section Simple Packages
;; 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}.