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: document package.el Date: Fri, 06 Aug 2010 16:42:54 -0600 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1281134589 14387 80.91.229.12 (6 Aug 2010 22:43:09 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 6 Aug 2010 22:43:09 +0000 (UTC) To: Emacs discussions Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Aug 07 00:43:08 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 1OhVd5-0002Mj-ME for ged-emacs-devel@m.gmane.org; Sat, 07 Aug 2010 00:43:08 +0200 Original-Received: from localhost ([127.0.0.1]:46074 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OhVd5-00058t-3C for ged-emacs-devel@m.gmane.org; Fri, 06 Aug 2010 18:43:07 -0400 Original-Received: from [140.186.70.92] (port=37766 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OhVcx-00057f-Tk for emacs-devel@gnu.org; Fri, 06 Aug 2010 18:43:01 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OhVcw-0008IF-2T for emacs-devel@gnu.org; Fri, 06 Aug 2010 18:42:59 -0400 Original-Received: from mx1.redhat.com ([209.132.183.28]:12372) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OhVcv-0008I4-Mb for emacs-devel@gnu.org; Fri, 06 Aug 2010 18:42:58 -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 o76Mgufp021700 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 6 Aug 2010 18:42:56 -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 o76MgtUL027154; Fri, 6 Aug 2010 18:42:56 -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 o76MgtQ9013092; Fri, 6 Aug 2010 18:42:55 -0400 Original-Received: by opsy.redhat.com (Postfix, from userid 500) id C5E413782ED; Fri, 6 Aug 2010 16:42:54 -0600 (MDT) X-Attribution: Tom 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:128410 Archived-At: 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 * 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. -@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-06 22:05:47 +0000 @@ -0,0 +1,149 @@ +@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/os +@node Packaging, Antinews, System Interface, Top +@chapter 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. + +@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 + + A package has a few attributes: + +@table @asis +@item Name +A string, the name of the package. + +@item Version +A version number, which is a dotted list of integers, like +@samp{1.2.0.3}. + +@item Brief description +This is shown to the user in the package menu buffer. It is just a +single line. + +@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. + +@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). + +@item Manual +A package can 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 +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. + +@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 a +some autoloads and little more. + +@node Simple Packages +@section 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 +@file{.el} 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. + +@node Multi-file Packages +@section 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 +@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. + + 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 +@file{-autoloads.el} file (e.g., +@file{superfrobnicator-autoloads.el}), 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. + +@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 is +not a dotted list of integers. + +@item 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: + +@smallexample +;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) +@end 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.