From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Tom Tromey Newsgroups: gmane.emacs.devel Subject: Re: document package.el Date: Sat, 21 Aug 2010 12:37:41 -0600 Message-ID: References: <878w4g66xb.fsf@stupidchicken.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1282415881 12204 80.91.229.12 (21 Aug 2010 18:38:01 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 21 Aug 2010 18:38:01 +0000 (UTC) Cc: Emacs discussions To: Chong Yidong Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Aug 21 20:38:00 2010 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Omsx4-0003ym-Tr for ged-emacs-devel@m.gmane.org; Sat, 21 Aug 2010 20:37:59 +0200 Original-Received: from localhost ([127.0.0.1]:37999 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Omsx4-0001Lb-0I for ged-emacs-devel@m.gmane.org; Sat, 21 Aug 2010 14:37:58 -0400 Original-Received: from [140.186.70.92] (port=54281 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Omswv-0001LP-Br for emacs-devel@gnu.org; Sat, 21 Aug 2010 14:37:53 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Omswr-0004bG-44 for emacs-devel@gnu.org; Sat, 21 Aug 2010 14:37:49 -0400 Original-Received: from mx1.redhat.com ([209.132.183.28]:53235) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Omswq-0004b4-QD for emacs-devel@gnu.org; Sat, 21 Aug 2010 14:37:45 -0400 Original-Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o7LIbhWn013373 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 21 Aug 2010 14:37:43 -0400 Original-Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o7LIbhkf011347; Sat, 21 Aug 2010 14:37:43 -0400 Original-Received: from opsy.redhat.com (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id o7LIbgcL026363; Sat, 21 Aug 2010 14:37:42 -0400 Original-Received: by opsy.redhat.com (Postfix, from userid 500) id CF87637897B; Sat, 21 Aug 2010 12:37:41 -0600 (MDT) X-Attribution: Tom In-Reply-To: <878w4g66xb.fsf@stupidchicken.com> (Chong Yidong's message of "Sun, 08 Aug 2010 19:06:24 -0400") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux) X-Scanned-By: MIMEDefang 2.67 on 10.5.11.12 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:128986 Archived-At: Here is an updated version of my proposed package.el documentation. I have tried to address all the comments. Tom === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2010-08-20 20:07:29 +0000 +++ doc/lispref/ChangeLog 2010-08-21 18:26:54 +0000 @@ -1,3 +1,14 @@ +2010-08-21 Tom Tromey + + * 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. + 2010-08-20 Eli Zaretskii * commands.texi (Misc Events): Add cross-references to where === 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. -@node Antinews, GNU Free Documentation License, System Interface, Top +@node 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 +@include 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 -@node System Interface, Antinews, Display, Top +@node 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-21 18:35:39 +0000 @@ -0,0 +1,189 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 2010 +@c 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 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. + +@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. +@end menu + +@node Packaging Basics +@section Packaging Basics +@cindex packaging basics + + A package has a few attributes: +@cindex package 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. + +@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. + +@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. + +@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. + +@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. +@end table + + Conceptually, a package goes through several state transitions (in +reality some of these transitions are grouped together): + +@table @asis +@item Download +Fetch the package from somewhere. + +@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. + +@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 + + 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. + +@node Simple Packages +@section Simple Packages +@cindex single file packages + + 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. + + The package system expects this @file{.el} file to conform to the +Emacs Lisp library header conventions. @xref{Library Headers}. + + 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: + +@smallexample +;;; superfrobnicator.el --- frobnicate and bifurcate flanges +@end smallexample + +the package name will be @samp{superfrobnicator}. + + 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. Each release of a package must be +accompanied by an increase in the 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 cookies at install time. +@xref{Autoload}. + +@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. + +@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. +@var{requirements} is a list of required packages and their versions. +@end defun + + 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}. +@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. + + 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. + + 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 the location-independent. One easy way to do this is to make +references to auxiliary data files relative to @var{load-file-name}. === modified file 'doc/lispref/tips.texi' --- doc/lispref/tips.texi 2010-06-23 03:36:56 +0000 +++ doc/lispref/tips.texi 2010-08-21 18:17:25 +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. + +@item 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 +cannot be parsed by @code{version-to-list}. @xref{Packaging Basics}. + +@item Package-Requires +If this exists, it names packages on which the current package depends +for proper operation. @xref{Packaging Basics}. 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: + +@smallexample +;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) +@end smallexample + +The package code automatically defines a package named @samp{emacs} +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.