bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics'

bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics'

[Drew Adams]

An anonymous user on Emacs Wiki updated a couple of my files to add
`Package-Requires' to the file headers, saying that this helped
MELPA/Marmalade.
 
I read the doc for `Package-Requires' at (elisp) `Library Headers' and
the cross-reffed doc `Packaging Basics', but that doc is unclear, and
some info seems to be missing.
 
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.
 
2. It does not say how these version-number strings are compared,
rendering this spec of the field almost meaningless.  `string-lessp'?
`version<'?  `version<='?  Something else?  What happens to a value of
""?  Or "0"?  What happens if the mandatory version string is missing
altogether?  What happens if a (FILE VERSION) has only the form FILE? 
 
3. Node `Packaging Basics', to which `Package-Requires' refers for more
information about this stuff says this:
 
  Version
     A version number, in a form that the function `version-to-list'
     understands (e.g., `11.86').  Each release of a package should be
     accompanied by an increase in the version number.
 
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.
 
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'?
 
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?
 
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).
 
Of course, there is no description of what "release" means, so maybe
uploading is not releasing.  No idea.  For my libraries and packages, I
generally do not care about "releasing" - I do not have releases.  How
does that use case fit the model and its requirements?
 
6. `Packaging Basics' also says this about "attribute" `Dependencies':
 
  Dependencies
     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.
 
Note: "_possibly_ including".  That means that "minimal acceptable
version numbers" are optional, _not_ mandatory, which contradicts what
is said in #1.
 
Also, nowhere is it said what such "attributes" are.  The term is quoted
here, as if this node were somehow defining the notion for readers, but
it is nowhere defined.  We list the attributes but we do not say what an
attribute is.
 
In particular, what is such an attribute in Emacs Lisp?  Where is it
stored and what does it look like (its type etc.)?
 
In general, the doc for this stuff is quite flaky and incomplete.
Please try to actually _specify_ what the Lisp thingies and concepts
are, rigorously.  That is the starting point for user explanations in
the manual.
 
7. I am mostly concerned about #1 and #6.  In my single-file package
`crosshairs.el', for example, the anonymous wiki user added this header
line:
 
;; Package-Requires: ((col-highlight "22.0") (hl-line+ "20120823") (vline
"1.10"))
 
I don't know where s?he got the version numbers used here.  Perhaps from
`Version' header fields in those files.  But I do not want package.el,
MELPA, etc. to think that crosshairs.el has a hard requirement for
version 22.0 of col-highlight.el, and so on.
 
It requires feature col-highlight, but not any particular version of
that library.  How can I specify that using `Package Requires'?
 
vline.el is not even my library.  I have no way of knowing, and a priori
I do not care, which minimal version of `vline.el' is required by
crosshairs.
 
And what happens if the pkg mgr finds only vline.el version 1.09 or
something?  Does that mean that it will not install crosshairs.el?
 
None of the many obvious questions like this that come up are answered
in the doc.  Just how does the pkg mgr handle these dependencies?  How
strict is it wrt the version numbers of required packages/files?  And
what does it do if it does not find the right version - stop? load an
"incorrect" version anyway?
 
I would not mind saying simplythat crosshairs.el requires
libraries/features col-highlight, hl-line+, and vline, without adding
any version info.  What happens if I do that?  #1 seems to say that such
a format is not supported (why not?).
 
8. If Emacs packaging is so rudimentary that it requires a VERSION field
in `Package Requires', then I suppose I can add a vacuous version
number, but (a) that just represents added noise and (b) what is the
vacuous entry?
 
If I cannot write `Package-Requires': (col-highlight hl-line+ vline)'
and I cannot write `Package-Requires: ((col-highlight) (hl-line+)
(vline))', can I write `Package-Requires: ((col-highlight "") (hl-line+
"") (vline ""))'?  Or must I write `Package-Requires: ((col-highlight
"0") (hl-line+ "0") (vline "0"))'?
 
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 info about this.
 
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?
 
What are the rules here?  And what happens when the rules are not
respected?  No info at all about this.
 
Please:
 
a. Let me know what the minimal requirements are, to enable users to
use, say, crosshairs.el with the Emacs pkg mgr (to permit use, e.g., on
MELPA).
 
b. Update the doc to provide complete and correct, non-ambiguous and
non-contradictory explanations of what is required wrt specifying
package dependencies in a file header.  For a single-file package, at
least.
 

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-18 on MS-W7-DANI
Bzr revision: 111265 eliz@gnu.org-20121218190556-x9wmq083vwecgu0f
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -Ic:/emacs/libs/libXpm-3.5.10/include -Ic:/emacs/libs/libXpm-3.5.10/src
 -Ic:/emacs/libs/libpng-dev_1.4.3-1_win32/include
 -Ic:/emacs/libs/zlib-dev_1.2.5-2_win32/include
 -Ic:/emacs/libs/giflib-4.1.4-1-lib/include
 -Ic:/emacs/libs/jpeg-6b-4-lib/include
 -Ic:/emacs/libs/tiff-3.8.2-1-lib/include
 -Ic:/emacs/libs/libxml2-2.7.8-w32-bin/include/libxml2
 -Ic:/emacs/libs/gnutls-3.0.9-w32-bin/include
 -Ic:/emacs/libs/libiconv-1.9.2-1-lib/include'
 

bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' &(elisp) `Packaging Basics'

[Drew Adams]

ping.

Could we please get some clarification on this?
Just what is the spec for `Package-Requires' etc.?

bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics'

[npostavs]

[-- 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

bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics'

[npostavs]

tags 13281 fixed
close 13281 25.2
quit

npostavs@users.sourceforge.net writes:

> 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).

Pushed to emacs-25 [1: ee1bd94dd0].

1: 2017-03-30 20:46:51 -0400 ee1bd94dd0ce427fcdfea33af38a4eaf47f911f0
  Improve packaging documentation