* lisp/progmodes/gud.el (gdb-script-syntax-propertize-function):

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

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 2010-2011  Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/package
@node Packaging, Antinews, System Interface, Top
@chapter Preparing Lisp code for distribution
@cindex packaging

  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.

  The following sections describe how to create a package, and how to
put it in a @dfn{package archive} for others to download.

@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
@cindex package attributes

  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 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
accompanied by an increase in the version number.

@item Brief description
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 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.

@item Dependencies
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

  Installing a package, either via the Package Menu, or via the
command @code{package-install-file}, 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).

  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.

@node Simple Packages
@section Simple Packages
@cindex single file packages

  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:

@example
@group
;;; superfrobnicator.el --- Frobnicate and bifurcate flanges

;; Copyright (C) 2011 Free Software Foundation, Inc.
@end group

;; Author: J. R. Hacker <jrh@@example.com>
;; Version: 1.3
;; Package-Requires: ((flange "1.0"))
;; Keywords: frobnicate

@dots{}

;;; Commentary:

;; This package provides a minor mode to frobnicate and/or
;; bifurcate any flanges you desire.  To activate it, just type
@dots{}

;;;###autoload
(define-minor-mode superfrobnicator-mode
@dots{}
@end example

  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 brief description is also taken from the first line.  Here, it
is @samp{Frobnicate and bifurcate flanges}.

  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.

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

  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}.

  @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 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
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 the content directory contains a file named @file{README}, this
file is used as the long description.

  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.

  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.

  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.

  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

To be done.