document package.el

[Tom Tromey]

I'd appreciate comments on this patch.

I finally found a little time to write some documentation for
package.el.

Tom

2010-08-06  Tom Tromey  <address@hidden>

        * vol2.texi (Top): Update.
        * vol1.texi (Top): Update.
        * tips.texi (Library Headers): Mention Package-Version and
        Package-Requires.
        * package.texi: New file.
        * os.texi (System Interface): Update pointers.
        * elisp.texi (Top): Link to new nodes.  Include package.texi.
        * anti.texi (Antinews): Update pointers.

=== modified file 'doc/lispref/anti.texi'
--- doc/lispref/anti.texi       2010-01-13 08:35:10 +0000
+++ doc/lispref/anti.texi       2010-07-30 00:05:33 +0000
@@ -6,7 +6,7 @@
 
 @c This node must have no pointers.
 
address@hidden Antinews, GNU Free Documentation License, System Interface, Top
address@hidden Antinews, GNU Free Documentation License, Packaging, Top
 @appendix Emacs 22 Antinews
 @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries
 @c with the above version number.

=== modified file 'doc/lispref/elisp.texi'
--- doc/lispref/elisp.texi      2010-07-10 18:52:53 +0000
+++ doc/lispref/elisp.texi      2010-07-31 01:32:13 +0000
@@ -159,6 +159,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1394,6 +1396,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+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.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1490,6 +1498,8 @@
 @include display.texi
 @include os.texi
 
address@hidden package.texi
+
 @c MOVE to Emacs Manual:  include misc-modes.texi
 
 @c appendices

=== modified file 'doc/lispref/os.texi'
--- doc/lispref/os.texi 2010-07-10 18:52:53 +0000
+++ doc/lispref/os.texi 2010-07-30 00:05:24 +0000
@@ -5,7 +5,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/os
address@hidden System Interface, Antinews, Display, Top
address@hidden System Interface, Packaging, Display, Top
 @chapter Operating System Interface
 
   This chapter is about starting and getting out of Emacs, access to

=== added file 'doc/lispref/package.texi'
--- doc/lispref/package.texi    1970-01-01 00:00:00 +0000
+++ doc/lispref/package.texi    2010-08-06 22:05:47 +0000
@@ -0,0 +1,149 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 2010
address@hidden   Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../../info/os
address@hidden Packaging, Antinews, System Interface, Top
address@hidden Preparing Lisp code for distribution
+
+  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.
+
+  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, for example, a package consisting solely of documentation.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Packaging Basics
address@hidden Packaging Basics
+
+  A package has a few attributes:
+
address@hidden @asis
address@hidden Name
+A string, the name of the package.
+
address@hidden Version
+A version number, which is a dotted list of integers, like
address@hidden
+
address@hidden Brief description
+This is shown to the user in the package menu buffer.  It is just a
+single line.
+
address@hidden 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.
+
address@hidden 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).
+
address@hidden Manual
+A package can include an info manual.
address@hidden table
+
+  Conceptually, a package goes through several state transitions (in
+reality some of these transitions are grouped together):
+
address@hidden @asis
address@hidden Download
+Fetch the package from somewhere.
+
address@hidden Install
+Untar 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.
+
address@hidden 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.
address@hidden table
+
+  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 a
+some autoloads and little more.
+
address@hidden Simple Packages
address@hidden Simple Packages
+
+  The simplest package consists of a single Emacs Lisp source file.
+In this case, all the attributes of the package are taken from this
+file.
+
+  The package system expects this @file{.el} file to conform to the
+Emacs Lisp library header conventions.  See @xref{Library Headers}.
+
+  The name of the package is the same as the base name of the
address@hidden file, as written in the first comment line.
+
+  The short description of the package is also taken from the first
+line of the file.
+
+  If the file has a ``Commentary'' header, then it is used as the long
+description.
+
+  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.
+
+  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.
+
+  A single-file package cannot have an info manual.
+
+  The file will be scanned for autoload comments at install time.
+
address@hidden Multi-file Packages
address@hidden 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 in a single
+directory, named after the package and version.  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
address@hidden
+
+  The package must include a @file{-pkg.el} file, named after the
+package.  In our example above, this file would be called
address@hidden  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.
+
+  If a @file{README} file exists in the content directory, then it 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}.
+
+  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.
+
+  The installation process will scan all the @file{.el} files in the
+package for autoload comments.  They are extracted into a
address@hidden file (e.g.,
address@hidden), so do not include a file of
+that name in your package.
+

=== modified file 'doc/lispref/tips.texi'
--- doc/lispref/tips.texi       2010-06-23 03:36:56 +0000
+++ doc/lispref/tips.texi       2010-07-31 18:43:10 +0000
@@ -1052,6 +1052,31 @@
 This field is important; it's how people will find your package when
 they're looking for things by topic area.  To separate the keywords, you
 can use spaces, commas, or both.
+
address@hidden Package-Version
+If @samp{Version} is not suitable for use by the package manager, then
+a package can define @samp{Package-Version}; it will be used instead.
+This is handy if @samp{Version} is an RCS id or something else that is
+not a dotted list of integers.
+
address@hidden Package-Requires
+If this exists, it names packages on which the current package
+depends for proper operation.  This is used by the package manager
+both at download time (to ensure that a complete set of packages is
+downloaded) and at activation time (to ensure that a package is
+activated if and only if all its dependencies have been).
+
+Its format is a list of lists.  The @code{car} of each sub-list is the
+name of a package, as a symbol.  The @code{cadr} of each sub-list is
+the minimum acceptable version number, as a string.  For instance:
+
address@hidden
+;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2"))
address@hidden smallexample
+
+The package code automatically defines a package named @samp{eamcs}
+with the version number of the currently running Emacs.  This can be
+used to require a minimal version of Emacs for a package.
 @end table
 
   Just about every Lisp library ought to have the @samp{Author} and

=== modified file 'doc/lispref/vol1.texi'
--- doc/lispref/vol1.texi       2010-07-10 18:52:53 +0000
+++ doc/lispref/vol1.texi       2010-07-31 01:32:31 +0000
@@ -180,6 +180,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1415,6 +1417,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+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.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.

=== modified file 'doc/lispref/vol2.texi'
--- doc/lispref/vol2.texi       2010-07-10 18:52:53 +0000
+++ doc/lispref/vol2.texi       2010-07-31 01:32:50 +0000
@@ -179,6 +179,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1414,6 +1416,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+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.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.