@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-2013 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
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
@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. @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
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: