From: Chong Yidong Date: Sun, 6 Mar 2011 15:54:36 +0000 (-0500) Subject: Improve packaging documentation. X-Git-Tag: emacs-pretest-24.0.90~104^2~275^2~667 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=120d9389bf24bd04e6eb25e52a8b43faeb77dad4;p=emacs.git Improve packaging documentation. * package.texi (Packaging, Packaging Basics, Simple Packages) (Multi-file Packages): Expand and clarify. (Package Archives): Temporary placeholder node. * elisp.texi (Top): Update node listing. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 7bb1919b837..5d28a90136e 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,11 @@ 2011-03-06 Chong Yidong + * package.texi (Packaging, Packaging Basics, Simple Packages) + (Multi-file Packages): Expand and clarify. + (Package Archives): Temporary placeholder node. + + * elisp.texi (Top): Update node listing. + * Makefile.in (srcs): Add package.texi. 2011-03-05 Chong Yidong diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index cc3ceb8003c..fc066526614 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1399,6 +1399,7 @@ Preparing Lisp code for distribution * 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. Starting Up Emacs diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 373e1e2b5c7..4de44fe165d 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -7,186 +7,223 @@ @chapter Preparing Lisp code for distribution @cindex packaging - 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. @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 + 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 and its capabilities. @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): + 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. -@table @asis -@item Download -Fetch the package from somewhere. +@node Simple Packages +@section Simple Packages +@cindex single file packages -@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 +;; 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. + 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}. - - 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. +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. - 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{.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. - 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. + 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. - 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)) @@ -194,3 +231,8 @@ For example: (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.