From: Tom Tromey <tromey@redhat.com>
To: Chong Yidong <cyd@stupidchicken.com>
Cc: Emacs discussions <emacs-devel@gnu.org>
Subject: Re: document package.el
Date: Sat, 21 Aug 2010 12:37:41 -0600 [thread overview]
Message-ID: <m31v9rvmkq.fsf@fleche.redhat.com> (raw)
In-Reply-To: <878w4g66xb.fsf@stupidchicken.com> (Chong Yidong's message of "Sun, 08 Aug 2010 19:06:24 -0400")
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 <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-20 Eli Zaretskii <eliz@gnu.org>
* 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.
next prev parent reply other threads:[~2010-08-21 18:37 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-08-06 22:42 document package.el Tom Tromey
2010-08-06 23:48 ` Phil Hagelberg
2010-08-09 16:22 ` Tom Tromey
2010-08-07 1:43 ` Christoph
2010-08-07 8:57 ` Geralt
2010-08-09 16:23 ` Tom Tromey
2010-08-26 23:27 ` Juri Linkov
2010-08-26 23:50 ` Stefan Monnier
2010-08-27 3:14 ` Christoph
2010-08-27 5:51 ` Uday S Reddy
2010-08-27 3:12 ` Christoph
2010-08-27 7:07 ` Uday S Reddy
2010-08-27 21:40 ` Phil Hagelberg
2010-08-28 17:34 ` Tom Tromey
2010-08-27 6:43 ` Uday S Reddy
2010-08-27 15:51 ` Tom Tromey
2010-08-27 16:17 ` Chong Yidong
2010-08-27 21:43 ` Richard Stallman
2010-08-27 22:58 ` Christoph
2010-08-28 7:25 ` Uday S Reddy
2010-08-07 7:47 ` Eli Zaretskii
2010-08-08 22:39 ` Chong Yidong
2010-08-09 16:24 ` Tom Tromey
2010-08-21 18:22 ` Tom Tromey
2010-08-21 18:51 ` Eli Zaretskii
2010-08-22 1:40 ` Tom Tromey
2010-08-08 23:06 ` Chong Yidong
2010-08-09 21:13 ` Tom Tromey
2010-08-21 18:37 ` Tom Tromey [this message]
2010-08-25 17:24 ` Chong Yidong
2010-08-25 17:34 ` Tom Tromey
2010-08-25 17:35 ` Chong Yidong
2010-08-17 14:37 ` Uday S Reddy
2010-08-17 15:57 ` Tom Tromey
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m31v9rvmkq.fsf@fleche.redhat.com \
--to=tromey@redhat.com \
--cc=cyd@stupidchicken.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.