From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics' Date: Wed, 26 Dec 2012 10:27:44 -0800 Message-ID: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1356546507 18511 80.91.229.3 (26 Dec 2012 18:28:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 26 Dec 2012 18:28:27 +0000 (UTC) To: 13281@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Dec 26 19:28:42 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Tnvib-0003mK-IG for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Dec 2012 19:28:41 +0100 Original-Received: from localhost ([::1]:55702 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TnviN-00045i-94 for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Dec 2012 13:28:27 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:46534) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TnviJ-000456-I1 for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:28:25 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TnviF-0008Qa-Sm for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:28:23 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:50661) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TnviF-0008QQ-Pw for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:28:19 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1Tnviw-0004Ie-76 for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:29:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 26 Dec 2012 18:29:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 13281 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.135654652716498 (code B ref -1); Wed, 26 Dec 2012 18:29:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 26 Dec 2012 18:28:47 +0000 Original-Received: from localhost ([127.0.0.1]:60912 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Tnvif-0004I2-VI for submit@debbugs.gnu.org; Wed, 26 Dec 2012 13:28:46 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:35013) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Tnvic-0004Ht-AC for submit@debbugs.gnu.org; Wed, 26 Dec 2012 13:28:44 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Tnvhs-0008Mo-Vi for submit@debbugs.gnu.org; Wed, 26 Dec 2012 13:27:59 -0500 Original-Received: from lists.gnu.org ([208.118.235.17]:37018) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Tnvhs-0008Ma-T5 for submit@debbugs.gnu.org; Wed, 26 Dec 2012 13:27:56 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:46345) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Tnvhr-00041E-9f for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:27:56 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Tnvhk-0008LN-F5 for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:27:55 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:36515) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Tnvhk-0008L7-5t for bug-gnu-emacs@gnu.org; Wed, 26 Dec 2012 13:27:48 -0500 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id qBQIRkhO004571 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Wed, 26 Dec 2012 18:27:47 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id qBQIRj3V029252 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Wed, 26 Dec 2012 18:27:46 GMT Original-Received: from abhmt109.oracle.com (abhmt109.oracle.com [141.146.116.61]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id qBQIRj2u019265 for ; Wed, 26 Dec 2012 12:27:45 -0600 Original-Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 26 Dec 2012 10:27:45 -0800 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac3jlrLK3CVAdbZpSJ2YJdN/WytNlA== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:69057 Archived-At: 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'