From: Tom Tromey <tromey@redhat.com>
To: Emacs discussions <emacs-devel@gnu.org>
Subject: document package.el
Date: Fri, 06 Aug 2010 16:42:54 -0600 [thread overview]
Message-ID: <m38w4jqs5t.fsf@fleche.redhat.com> (raw)
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 <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.
=== 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.
next reply other threads:[~2010-08-06 22:42 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-08-06 22:42 Tom Tromey [this message]
2010-08-06 23:48 ` document package.el 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
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=m38w4jqs5t.fsf@fleche.redhat.com \
--to=tromey@redhat.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.