From: npostavs@users.sourceforge.net
To: "Drew Adams" <drew.adams@oracle.com>
Cc: 13281@debbugs.gnu.org
Subject: bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics'
Date: Sat, 25 Mar 2017 01:04:28 -0400 [thread overview]
Message-ID: <87o9wq0wwz.fsf@users.sourceforge.net> (raw)
In-Reply-To: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> (Drew Adams's message of "Wed, 26 Dec 2012 10:27:44 -0800")
[-- Attachment #1: Type: text/plain, Size: 3298 bytes --]
tags 13281 patch
quit
"Drew Adams" <drew.adams@oracle.com> writes:
>
> 1. Node `Package-Requires' says that this file-header field must be a
> list of lists, each of whose cadr is a version number (string). IOW,
> the version number seems to be mandatory: it must be present.
It's not mandatory, I've clarified this in the patch below.
> 2. It does not say how these version-number strings are compared,
> rendering this spec of the field almost meaningless. `string-lessp'?
> `version<'? `version<='?
I added a mention of `version-to-list' in the patch. Along with the
existing text saying "the minimum acceptable version number" I think
that makes the meaning clear.
> What is the relation between this `Version' "attribute" and the
> file-header `Version' field? None? Where does the attribute value come
> from, if not from that field? No info at all about this.
`(elisp) Simple Packages' says
The package's attributes are taken from the various headers
`(elisp) Multi-file Packages' says
One of the files in the content directory must be named
`NAME-pkg.el'. It must contain a single Lisp form, consisting of a
call to the function `define-package', described below. This defines
the package's version, brief description, and requirements.
I added the word "attributes" to the last sentence in the patch. I
think that makes it clear.
>
> 4. #3 means that a library must use a version number that is
> recognizable by `version-to-list'. And what if it does not - what
> happens? How to refer to a required library, using `Package-Requires',
> if that required library does not have a `Version' file-header entry
> that corresponds to `version-to-list'?
`(elisp) Simple Packages' says
The version number comes from the `Package-Version' header, if it
exists, or from the `Version' header otherwise. One or the other
_must_ be present.
> 5. Why does a package need to be released in "releases", each of which
> is accompanied by an increase in the version number? And is it really
> even true that this is a hard requirement?
I added an explanation in the patch about why it's needed.
>
> This does not seem to be a requirement for multiple-file packages. Why
> should it be a requirement for single-file packages?
>
> I know it is not required for multi-file packages because I have some
> that work fine with MELPA etc., and their `Version' numbers are not
> incremented each time the package files are uploaded, which is daily
> (automatically).
This doesn't cover MELPA though. MELPA automatically adds a version
number based on the timestamp of when the source is retrieved. The
manual does not document MELPA as it is not part of GNU Emacs.
>
> And what about inherited dependencies? If hl-line+.el requires
> hl-line.el, do I need to flatten the `Package-Requires' for
> crosshairs.el, to include hl-line?
No. I added the word "recursively" to the "Dependencies"
attribute description in the patch.
> And what if the list of dependencies is long - do I need to write them
> all on a single line, making the line-width far too wide for the file?
> If not, what do `Package-Requires' continuation lines look like?
It must be on a single line. I've added a mention about that in the
patch.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 3462 bytes --]
From 2bd4a0c1720a5c22d8f07cfd47b4a3494d7503d1 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sat, 25 Mar 2017 00:58:44 -0400
Subject: [PATCH v1] Improve packaging documentation
* doc/lispref/package.texi (Packaging Basics):
* doc/lispref/tips.texi (Library Headers): Clarify some header
formats, relation between file headers and package
attributes (Bug#13281).
---
doc/lispref/package.texi | 12 +++++++-----
doc/lispref/tips.texi | 11 +++++++----
2 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 6066ea9a93..b0dbe4d0a6 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -54,7 +54,8 @@ Packaging Basics
@item Version
A version number, in a form that the function @code{version-to-list}
understands (e.g., @samp{11.86}). Each release of a package should be
-accompanied by an increase in the version number.
+accompanied by an increase in the version number so that it will be
+recognized as an upgrade by users querying the package archive.
@item Brief description
This is shown when the package is listed in the Package Menu. It
@@ -71,8 +72,9 @@ Packaging Basics
A list of other packages (possibly including minimal acceptable
version numbers) on which this package depends. The list may be
empty, meaning this package has no dependencies. Otherwise,
-installing this package also automatically installs its dependencies;
-if any dependency cannot be found, the package cannot be installed.
+installing this package also automatically installs its dependencies,
+recursively; if any dependency cannot be found, the package cannot be
+installed.
@end table
@cindex content directory, package
@@ -212,8 +214,8 @@ Multi-file Packages
One of the files in the content directory must be named
@file{@var{name}-pkg.el}. It must contain a single Lisp form,
consisting of a call to the function @code{define-package}, described
-below. This defines the package's version, brief description, and
-requirements.
+below. This defines the package's attributes: version, brief
+description, and requirements.
For example, if we distribute version 1.3 of the superfrobnicator as
a multi-file package, the tar file would be
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index bd560370f7..0b3c017b10 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -1047,12 +1047,15 @@ Library Headers
of packages is downloaded) and at activation time (to ensure that a
package is only activated 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:
+Its format is a list of lists on a single line. 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
+that can be parse by @code{version-to-list}. An entry that lacks a
+version (i.e., an entry which is just a symbol, or a sub-list of one
+element) is equivalent to entry with version "0". For instance:
@smallexample
-;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2"))
+;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq))
@end smallexample
The package code automatically defines a package named @samp{emacs}
--
2.11.1
next prev parent reply other threads:[~2017-03-25 5:04 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-12-26 18:27 bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics' Drew Adams
2017-03-25 5:04 ` npostavs [this message]
2017-03-31 0:54 ` npostavs
[not found] <<694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com>
2013-07-19 15:13 ` bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' &(elisp) " Drew Adams
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
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87o9wq0wwz.fsf@users.sourceforge.net \
--to=npostavs@users.sourceforge.net \
--cc=13281@debbugs.gnu.org \
--cc=drew.adams@oracle.com \
/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 public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).