@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 packaging
+@cindex package
+@cindex Lisp package
Emacs provides a standard way to distribute Emacs Lisp code to
users. A @dfn{package} is a collection of one or more files,
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.
@node Packaging Basics
@section Packaging Basics
-@cindex packaging basics
@cindex package attributes
+@cindex package name
+@cindex package version
+@cindex dependencies
+@cindex package dependencies
A package is either a @dfn{simple package} or a @dfn{multi-file
package}. A simple package is stored in a package archive as a single
@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
if any dependency cannot be found, the package cannot be installed.
@end table
- Installing a package, either via the Package Menu, or via the
-command @code{package-install-file}, creates a subdirectory of
+@cindex content directory, package
+ 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).
+@cindex package autoloads
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 @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
-@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
-@cindex single file packages
+@cindex single file package
+@cindex simple package
A simple package consists of a single Emacs Lisp source file. The
file must conform to the Emacs Lisp library header conventions
@node Multi-file Packages
@section Multi-file Packages
-@cindex multi-file packages
+@cindex multi-file package
A multi-file package is less convenient to create than a single-file
package, but it offers more features: it can include multiple Emacs
If the content directory contains a file named @file{dir}, this is
assumed to be an Info directory file made with @command{install-info}.
@xref{Invoking install-info, Invoking install-info, Invoking
-install-info, texinfo, Texinfo}. The Info files listed in this
-directory file should also be present in the content directory. In
-this case, Emacs will automatically add the content directory to
-@code{Info-directory-list} when the package is activated.
+install-info, texinfo, Texinfo}. The relevant Info files should also
+be present in the content directory. In this case, Emacs will
+automatically add the content directory to @code{Info-directory-list}
+when the package is activated.
Do not include any @file{.elc} files in the package. Those are
created when the package is installed. Note that there is no way to
@node Package Archives
@section Creating and Maintaining Package Archives
-
-To be done.
+@cindex package archive
+
+ 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
+section describes how to set up and maintain a package archive.
+
+@cindex base location, package archive
+@defopt 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 @code{(@var{id} . @var{location})}, where @var{id} is the name of
+the archive (a string) and @var{location} is its @dfn{base location}
+(a string).
+
+If the base location starts with @samp{http:}, it is treated as a HTTP
+URL, and packages are downloaded from this archive via HTTP (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.
+@end defopt
+
+ 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
+@code{package-x} library. This is included with Emacs, but not loaded
+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:
+
+@defopt 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 @code{package-x} library
+will use this base location.
+
+The directory name should be absolute. You may specify a remote name,
+such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the
+package archive is on a different machine. @xref{Remote Files,,
+Remote Files, emacs, The GNU Emacs Manual}.
+@end defopt
+
+@deffn Command package-upload-file filename
+This command prompts for @var{filename}, a file name, and uploads that
+file to @code{package-archive-upload-base}. The file must be either a
+simple package (a @file{.el} file) or a multi-file package (a
+@file{.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 @code{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).
+@end deffn
+
+@deffn Command package-upload-buffer
+This command is similar to @code{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
+@file{.el} file) or a multi-file package (a @file{.tar} file);
+otherwise, an error is raised.
+@end deffn
+
+@noindent
+After you create an archive, remember that it is not accessible in the
+Package Menu interface unless it is in @code{package-archives}.