Mercurial > emacs
changeset 109988:ae3fecdc3276
merge trunk
| author | Kenichi Handa <handa@m17n.org> |
|---|---|
| date | Thu, 26 Aug 2010 09:28:08 +0900 |
| parents | 2e817b887353 (current diff) a44dc3503539 (diff) |
| children | b9af37ce659c 7ab569e9f738 |
| files | |
| diffstat | 8 files changed, 261 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/lispref/ChangeLog Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/ChangeLog Thu Aug 26 09:28:08 2010 +0900 @@ -1,3 +1,14 @@ +2010-08-25 Tom Tromey <tromey@redhat.com> + + * 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-25 Eli Zaretskii <eliz@gnu.org> * processes.texi (Filter Functions): Fix last change.
--- a/doc/lispref/anti.texi Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/anti.texi Thu Aug 26 09:28:08 2010 +0900 @@ -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.
--- a/doc/lispref/elisp.texi Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/elisp.texi Thu Aug 26 09:28:08 2010 +0900 @@ -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
--- a/doc/lispref/os.texi Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/os.texi Thu Aug 26 09:28:08 2010 +0900 @@ -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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/package.texi Thu Aug 26 09:28:08 2010 +0900 @@ -0,0 +1,197 @@ +@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 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: + +@smallexample +(defconst superfrobnicator-base (file-name-directory load-file-name)) + +(defun superfrobnicator-fetch-image (file) + (expand-file-name file superfrobnicator-base)) +@end smallexample
--- a/doc/lispref/tips.texi Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/tips.texi Thu Aug 26 09:28:08 2010 +0900 @@ -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
--- a/doc/lispref/vol1.texi Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/vol1.texi Thu Aug 26 09:28:08 2010 +0900 @@ -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.
--- a/doc/lispref/vol2.texi Wed Aug 25 17:15:45 2010 +0900 +++ b/doc/lispref/vol2.texi Thu Aug 26 09:28:08 2010 +0900 @@ -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.