@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 2010, 2011
-@c 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 for Emacs Lisp code to be distributed
-to users. This approach lets users easily download, install,
-uninstall, and upgrade Lisp code that they might want to use.
+ Emacs provides a standard way to distribute Emacs Lisp code to
+users. A @dfn{package} is a collection of one or more files,
+formatted and bundled in such a way that users can easily download,
+install, uninstall, and upgrade it.
- A @dfn{package} is simply one or more files, formatted and bundled
-in a particular way. Typically a package includes primarily Emacs
-Lisp code, but it is possible to create other kinds of packages as
-well.
+ 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.
* Simple Packages:: How to package a single .el file.
* Multi-file Packages:: How to package multiple files.
+* Package Archives:: Maintaining package archives.
@end menu
@node Packaging Basics
@section Packaging Basics
-@cindex packaging basics
-
- A package has a few attributes:
@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
+Emacs Lisp file, while a multi-file package is stored as a tar file
+(containing multiple Lisp files, and possibly non-Lisp files such as a
+manual).
+
+ In ordinary usage, the difference between simple packages and
+multi-file packages is relatively unimportant; the Package Menu
+interface makes no distinction between them. However, the procedure
+for creating them differs, as explained in the following sections.
+
+ Each package (whether simple or multi-file) has certain
+@dfn{attributes}:
@table @asis
@item Name
-A string, the name of the package. This attribute is mandatory. If
-it does not exist, the package cannot be installed by the package
-manager.
+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, which is anything that can be parsed by
-@code{version-to-list}. This attribute is mandatory. If it does not
-exist, the package cannot be installed by the package manager.
+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
+accompanied by an increase in the version number.
@item Brief description
-This is shown to the user in the package menu buffer. It is just a
-single line. On a terminal with 80 characters per line, there are
-only 36 characters available in the package menu mode for showing the
-brief description, so it is best to keep it very brief. If no brief
-name is given, an empty string is used.
+This is shown when the package is listed in the Package Menu. It
+should occupy a single line, ideally in 36 characters or less.
@item Long description
-This can be a @file{README} file or the like. This is available to
-the user before the package is installed, via the package menu. It
-should more fully describe the package and its capabilities, so a user
-can read it to decide whether he wants to install the package. This
-attribute is optional.
+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's capabilities and how to begin using it
+once it is installed.
@item Dependencies
-This is a list of other packages and their minimal acceptable
-versions. This is used both at download time (to make sure all the
-needed code is available) and at activation time (to ensure a package
-is only activated if all its dependencies have been successfully
-activated). This attribute is optional.
-
-@item Manual
-A package can optionally include an Info manual.
+A list of other packages (possibly including minimal acceptable
+version numbers) on which this package depends. The list may be
+empty, meaning this package has no dependencies. Otherwise,
+installing this package also automatically installs its dependencies;
+if any dependency cannot be found, the package cannot be installed.
@end table
- Conceptually, a package goes through several state transitions (in
-reality some of these transitions are grouped together):
+@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
+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}). 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
-@table @asis
-@item Download
-Fetch the package from somewhere.
+@node Simple Packages
+@section Simple Packages
+@cindex single file package
+@cindex simple package
-@item Install
-Unpack the package, or write a @file{.el} file into the appropriate
-install directory. This step also includes extracting autoloads and
-byte-compiling the Emacs Lisp code.
+ A simple package consists of a single Emacs Lisp source file. The
+file must conform to the Emacs Lisp library header conventions
+(@pxref{Library Headers}). The package's attributes are taken from
+the various headers, as illustrated by the following example:
-@item Activate
-Update @code{load-path} and @code{Info-directory-list} and evaluate
-the autoloads, so that the package is ready for the user to use.
-@end table
+@example
+@group
+;;; superfrobnicator.el --- Frobnicate and bifurcate flanges
- It is best for users if packages do not do too much work at
-activation time. The best approach is to have activation consist of
-some autoloads and little more.
+;; Copyright (C) 2011 Free Software Foundation, Inc.
+@end group
-@node Simple Packages
-@section Simple Packages
-@cindex single file packages
+;; Author: J. R. Hacker <jrh@@example.com>
+;; Version: 1.3
+;; Package-Requires: ((flange "1.0"))
+;; Keywords: frobnicate
- The simplest package consists of a single Emacs Lisp source file.
-In this case, all the attributes of the package (@pxref{Packaging
-Basics}) are taken from this file.
+@dots{}
- The package system expects this @file{.el} file to conform to the
-Emacs Lisp library header conventions. @xref{Library Headers}.
+;;; Commentary:
- The name of the package is the same as the base name of the
-@file{.el} file, as written in the first comment line. For example,
-given the header line:
+;; This package provides a minor mode to frobnicate and/or
+;; bifurcate any flanges you desire. To activate it, just type
+@dots{}
-@smallexample
-;;; superfrobnicator.el --- frobnicate and bifurcate flanges
-@end smallexample
+;;;###autoload
+(define-minor-mode superfrobnicator-mode
+@dots{}
+@end example
-the package name will be @samp{superfrobnicator}.
+ The name of the package is the same as the base name of the file, as
+written on the first line. Here, it is @samp{superfrobnicator}.
- The short description of the package is also taken from the first
-line of the file.
+ The brief description is also taken from the first line. Here, it
+is @samp{Frobnicate and bifurcate flanges}.
- If the file has a ``Commentary'' header, then it is used as the long
-description.
+ The version number comes from the @samp{Package-Version} header, if
+it exists, or from the @samp{Version} header otherwise. One or the
+other @emph{must} be present. Here, the version number is 1.3.
- The version of the package comes either from the ``Package-Version''
-header, if it exists, or from the ``Version'' header. A package is
-required to have a version number. Each release of a package must be
-accompanied by an increase in the version number.
+ If the file has a @samp{;;; Commentary:} section, this section is
+used as the long description. (When displaying the description, Emacs
+omits the @samp{;;; Commentary:} line, as well as the leading comment
+characters in the commentary itself.)
- If the file has a ``Package-Requires'' header, then that is used as
-the package dependencies. Otherwise, the package is assumed not to
-have any dependencies.
+ If the file has a @samp{Package-Requires} header, that is used as
+the package dependencies. In the above example, the package depends
+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.
- A single-file package cannot have an Info manual.
+ 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 will be scanned for autoload cookies at install time.
-@xref{Autoload}.
+ @xref{Package Archives}, for a explanation of how to add a
+single-file package to a package archive.
@node Multi-file Packages
@section Multi-file Packages
-@cindex multi-file packages
-
- A multi-file package is just a @file{.tar} file. While less
-convenient to create than a single-file package, a multi-file package
-also offers more features: it can include an Info manual, multiple
-Emacs Lisp files, and also other data files needed by a package.
-
- The contents of the @file{.tar} file must all appear beneath a
-single directory, named after the package and version. Files can
-appear in subdirectories of this top-most directory, but Emacs Lisp
-code will only be found (and thus byte-compiled) at the top-most
-level. Also, the @file{.tar} file is typically also given this same
-name. For example, if you are distributing version 1.3 of the
-superfrobnicator, the package file would be named
-``superfrobnicator-1.3.tar'' and the contents would all appear in the
-directory @file{superfrobnicator-1.3} in that @file{.tar}.
-
- The package must include a @file{-pkg.el} file, named after the
-package. In our example above, this file would be called
-@file{superfrobnicator-pkg.el}. This file must have a single form in
-it, a call to @code{define-package}. The package dependencies and
-brief description are taken from this form.
+@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
+Lisp files, an Info manual, and other file types (such as images).
+
+ Prior to installation, a multi-file package is stored in a package
+archive as a tar file. The tar file must be named
+@file{@var{name}-@var{version}.tar}, where @var{name} is the package
+name and @var{version} is the version number. Its contents, once
+extracted, must all appear in a directory named
+@file{@var{name}-@var{version}}, the @dfn{content directory}
+(@pxref{Packaging Basics}). Files may also extract into
+subdirectories of the content directory.
+
+ One of the files in the content directory must be named
+@file{@var{name}-pkg.el}. It must contain a single Lisp form,
+consisting of a call to the function @code{define-package}, described
+below. This defines the package's version, brief description, and
+requirements.
+
+ For example, if we distribute version 1.3 of the superfrobnicator as
+a multi-file package, the tar file would be
+@file{superfrobnicator-1.3.tar}. Its contents would extract into the
+directory @file{superfrobnicator-1.3}, and one of these would be the
+file @file{superfrobnicator-pkg.el}.
@defun define-package name version &optional docstring requirements
-Define a package. @var{name} is the name of the package, a string.
-@var{version} is the package's version, a string. It must be in a
-form that can be understood by @code{version-to-list}.
-@var{docstring} is the short description of the package.
+This function defines a package. @var{name} is the package name, a
+string. @var{version} is the version, as a string of a form that can
+be understood by the function @code{version-to-list}. @var{docstring}
+is the brief description.
+
@var{requirements} is a list of required packages and their versions.
+Each element in this list should have the form @code{(@var{dep-name}
+@var{dep-version})}, where @var{dep-name} is a symbol whose name is
+the dependency's package name, and @var{dep-version} is the
+dependency's version (a string).
@end defun
- If a @file{README} file exists in the content directory, then it is
-used as the long description.
+ If the content directory contains a file named @file{README}, this
+file is used as the long description.
- If the package has an Info manual, you should distribute the needed
-info files, plus a @file{dir} file made with @command{install-info}.
+ 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}.
+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 will be
-created at install time. Note that there is no way to control the
-order in which files are byte-compiled; your package must be robust
-here.
+ 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
+control the order in which files are byte-compiled.
- The installation process will scan all the @file{.el} files in the
-package for autoload cookies. @xref{Autoload}. They are extracted
-into a @file{-autoloads.el} file (e.g.,
-@file{superfrobnicator-autoloads.el}), so do not include a file of
-that name in your package.
+ Do not include any file named @file{@var{name}-autoloads.el}. This
+file is reserved for the package's autoload definitions
+(@pxref{Packaging Basics}). It is created automatically when the
+package is installed, by searching all the Lisp files in the package
+for autoload magic comments.
- Any other files in the @file{.tar} file are simply unpacked when the
-package is installed. This can be useful if your package needs
-auxiliary data files --- e.g., icons or sounds.
-
- Emacs Lisp code installed via the package manager must take special
-care to be location-independent. One easy way to do this is to make
-references to auxiliary data files relative to @var{load-file-name}.
-For example:
+ If the multi-file package contains auxiliary data files (such as
+images), the package's Lisp code can refer to these files via the
+variable @code{load-file-name} (@pxref{Loading}). Here is an example:
@smallexample
(defconst superfrobnicator-base (file-name-directory load-file-name))
(defun superfrobnicator-fetch-image (file)
(expand-file-name file superfrobnicator-base))
@end smallexample
+
+@node Package Archives
+@section Creating and Maintaining Package Archives
+@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}.