Merge from emacs-24

[gnu-emacs] / doc / lispref / package.texi

diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 62fbc2a9a078ecd368acfd53870c57d62eb72021..c92497a8ce3c1950009673ef63612b2c099e0a7e 100644 (file)
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -1,9 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 2010-2011  Free Software Foundation, Inc.
+@c Copyright (C) 2010-2014 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @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
 @chapter Preparing Lisp code for distribution
 @cindex package
 @cindex Lisp package


@@ -15,6 +14,8 @@ install, uninstall, and upgrade it.
 
   The following sections describe how to create a package, and how to
 put it in a @dfn{package archive} for others to download.
 
   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.
 
 @menu
 * Packaging Basics::        The basic concepts of Emacs Lisp packages.


@@ -47,12 +48,12 @@ for creating them differs, as explained in the following sections.
 
 @table @asis
 @item Name
 
 @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}
 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
 accompanied by an increase in the version number.
 
 @item Brief description


@@ -63,7 +64,8 @@ should occupy a single line, ideally in 36 characters or less.
 This is shown in the buffer created by @kbd{C-h P}
 (@code{describe-package}), following the package's brief description
 and installation status.  It normally spans multiple lines, and should
 This is shown in the buffer created by @kbd{C-h P}
 (@code{describe-package}), following the package's brief description
 and installation status.  It normally spans multiple lines, and should

-fully describe the package and its capabilities.
+fully describe the package's capabilities and how to begin using it
+once it is installed.

 
 @item Dependencies
 A list of other packages (possibly including minimal acceptable
 
 @item Dependencies
 A list of other packages (possibly including minimal acceptable


@@ -74,11 +76,11 @@ if any dependency cannot be found, the package cannot be installed.
 @end table
 
 @cindex content directory, package
 @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
 @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).
 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).


@@ -90,17 +92,34 @@ definitions are saved to a file named @file{@var{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
 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.  @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
 
 @node Simple Packages
 @section Simple Packages


@@ -122,7 +141,8 @@ the various headers, as illustrated by the following example:
 ;; Author: J. R. Hacker <jrh@@example.com>
 ;; Version: 1.3
 ;; Package-Requires: ((flange "1.0"))
 ;; 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{}
 
 
 @dots{}
 


@@ -158,6 +178,11 @@ on the @samp{flange} package, version 1.0 or higher.  @xref{Library
 Headers}, for a description of the @samp{Package-Requires} header.  If
 the header is omitted, the package has no dependencies.
 
 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}.
   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}.


@@ -246,7 +271,7 @@ variable @code{load-file-name} (@pxref{Loading}).  Here is an example:
   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:
   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
 section describes how to set up and maintain a package archive.
 
 @cindex base location, package archive


@@ -275,8 +300,8 @@ 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
 @code{package-x} library.  This is included with Emacs, but not loaded
 
   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:
 
 @xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}.
 Once loaded, you can make use of the following:
 


@@ -317,3 +342,38 @@ otherwise, an error is raised.
 @noindent
 After you create an archive, remember that it is not accessible in the
 Package Menu interface unless it is in @code{package-archives}.
 @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}.