From unknown Wed Jun 25 03:56:48 2025 X-Loop: help-debbugs@gnu.org Subject: bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics' 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: To: 13281@debbugs.gnu.org X-Debbugs-Original-To: Received: via spool by submit@debbugs.gnu.org id=B.135654652716498 (code B ref -1); Wed, 26 Dec 2012 18:29:02 +0000 Received: (at submit) by debbugs.gnu.org; 26 Dec 2012 18:28:47 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-104.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY, USER_IN_WHITELIST autolearn=unavailable version=3.3.2 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 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 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 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 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 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 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 Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 26 Dec 2012 10:27:45 -0800 From: "Drew Adams" Date: Wed, 26 Dec 2012 10:27:44 -0800 Message-ID: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit 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-Received-From: 208.118.235.17 X-Spam-Score: -6.1 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.1 (------) 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' From unknown Wed Jun 25 03:56:48 2025 X-Loop: help-debbugs@gnu.org Subject: bug#13281: 24.3.50;"Package-Requires" missing info in (elisp) `Library Headers' &(elisp) `Packaging Basics' Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 19 Jul 2013 15:14:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13281 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 13281@debbugs.gnu.org Received: via spool by 13281-submit@debbugs.gnu.org id=B13281.137424679815015 (code B ref 13281); Fri, 19 Jul 2013 15:14:01 +0000 Received: (at 13281) by debbugs.gnu.org; 19 Jul 2013 15:13:18 +0000 Received: from localhost ([127.0.0.1]:37642 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V0CMv-0003u4-RE for submit@debbugs.gnu.org; Fri, 19 Jul 2013 11:13:18 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:30739) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V0CMr-0003ta-NI for 13281@debbugs.gnu.org; Fri, 19 Jul 2013 11:13:15 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r6JFD6gr022000 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for <13281@debbugs.gnu.org>; Fri, 19 Jul 2013 15:13:07 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r6JFD5WT023386 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for <13281@debbugs.gnu.org>; Fri, 19 Jul 2013 15:13:06 GMT Received: from abhmt104.oracle.com (abhmt104.oracle.com [141.146.116.56]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r6JFD5ir005197 for <13281@debbugs.gnu.org>; Fri, 19 Jul 2013 15:13:05 GMT MIME-Version: 1.0 Message-ID: <171b0e59-3ff8-4972-b911-f3f0a7c47b73@default> Date: Fri, 19 Jul 2013 08:13:04 -0700 (PDT) From: Drew Adams References: <<694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com>> In-Reply-To: <<694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.7 (607090) [OL 12.0.6668.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Spam-Score: -2.7 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.7 (--) ping. Could we please get some clarification on this? Just what is the spec for `Package-Requires' etc.? From unknown Wed Jun 25 03:56:48 2025 X-Loop: help-debbugs@gnu.org Subject: bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics' Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 25 Mar 2017 05:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13281 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 13281@debbugs.gnu.org Received: via spool by 13281-submit@debbugs.gnu.org id=B13281.149041819313203 (code B ref 13281); Sat, 25 Mar 2017 05:04:02 +0000 Received: (at 13281) by debbugs.gnu.org; 25 Mar 2017 05:03:13 +0000 Received: from localhost ([127.0.0.1]:43073 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crdr6-0003Qo-SZ for submit@debbugs.gnu.org; Sat, 25 Mar 2017 01:03:13 -0400 Received: from mail-it0-f51.google.com ([209.85.214.51]:36365) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crdr5-0003QX-6u; Sat, 25 Mar 2017 01:03:11 -0400 Received: by mail-it0-f51.google.com with SMTP id w124so27747258itb.1; Fri, 24 Mar 2017 22:03:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=NWUZ1MtKxagqov3Cv9gpIT4H+gHmRD0R9NlRbEirutw=; b=NRnCU68rP4uz+ZYSp9wLrF2VxFlhb2WZAagaxVTulTSrsaPLx0AUc7sLJGF71K4gAi XrcT8QyLwPUncSkaAnNkM8PQDQ59kJ97O/iuWrpGixuxcRfEWWb4HBGPov5lS/XG0QC3 K//yy/Ik+u9UvEaF82vMYKSGdTS9uvhh/kXYwrCSSDXX01auYVARMUCzLSFwr0uTwj99 tzrm7ptW7icYSLf2gBqxVb9dHHOlvNtWpCZwvRO4kUTVqV48TTsdeyRpLzZBHslthb9+ Xtg3PoSDaNWQCGo71jKZ1DdK0PE+bBNNNbVlrEKeeLqYLj57NYjCukSRQVTdW1ob46JK lvwg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=NWUZ1MtKxagqov3Cv9gpIT4H+gHmRD0R9NlRbEirutw=; b=YQzSEdZuqwdGyNjlf9OmgqjVeOEd42CH0Z1X5Yo77K/qCgVmjqZInErz1Xrq/QO8Ms JBl2AaHGFSWYffUAdFAsxsxsFSxT1wP/ie4jyoJ2vsW0oBNQ9y0K49Ysa+OoSdwpFU3K bSt6Rho/ErTKis1mbxjYT6xxAU5Zl4B1wwrkiKFlryxnK2CVk1IkSMsA9E5snFukYM0X hnWCE0lgzFkT99Tm6HwujapIi8o1Kydzy2nCuH9J18nP6tp9bwfap5ujFhXqkGfTH6zT cS6gwhe/WltvhfS/vtbQIvNh5L64sFxB8doxKi/X3n1X7MRovzjNedwWhTprFXqNIA57 FlzA== X-Gm-Message-State: AFeK/H0zBcftuad/MT0Hd/IO1Op+c/193UqxK7fozIqVw1d6X4dg1LoTc3k/eKK4WRpqvg== X-Received: by 10.36.220.6 with SMTP id q6mr536563itg.77.1490418185530; Fri, 24 Mar 2017 22:03:05 -0700 (PDT) Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id v185sm2046999itf.11.2017.03.24.22.03.04 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 24 Mar 2017 22:03:04 -0700 (PDT) From: npostavs@users.sourceforge.net References: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> Date: Sat, 25 Mar 2017 01:04:28 -0400 In-Reply-To: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> (Drew Adams's message of "Wed, 26 Dec 2012 10:27:44 -0800") Message-ID: <87o9wq0wwz.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: 0.2 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.2 (/) --=-=-= Content-Type: text/plain tags 13281 patch quit "Drew Adams" 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. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=v1-0001-Improve-packaging-documentation.patch Content-Description: patch >From 2bd4a0c1720a5c22d8f07cfd47b4a3494d7503d1 Mon Sep 17 00:00:00 2001 From: Noam Postavsky 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 --=-=-=-- From unknown Wed Jun 25 03:56:48 2025 X-Loop: help-debbugs@gnu.org Subject: bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics' Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 31 Mar 2017 00:54:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13281 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: "Drew Adams" Cc: 13281@debbugs.gnu.org Received: via spool by 13281-submit@debbugs.gnu.org id=B13281.149092158917709 (code B ref 13281); Fri, 31 Mar 2017 00:54:02 +0000 Received: (at 13281) by debbugs.gnu.org; 31 Mar 2017 00:53:09 +0000 Received: from localhost ([127.0.0.1]:53342 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ctkoO-0004bT-V7 for submit@debbugs.gnu.org; Thu, 30 Mar 2017 20:53:09 -0400 Received: from mail-it0-f52.google.com ([209.85.214.52]:36741) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ctkoN-0004b9-I8; Thu, 30 Mar 2017 20:53:07 -0400 Received: by mail-it0-f52.google.com with SMTP id e75so4446819itd.1; Thu, 30 Mar 2017 17:53:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=KQX1+fwLRww0qPIq6y9XkUyARq6GhdiqbQnB3Npgv2Y=; b=FXxSOC00YdFpEjXLZp/1j0OnMXu7b1O/0NScoTQkZ3RqMpETG5wWPn08kkTOypzF5f LXDzMIb4D6AcS2qLlCLZbTrGwMqrvY/GVCOYP1jR3LFWHMYZAj7OF5GIvIRmu5/5+ExG CBEPlfriWy4HNrm+ABrMDm0bBY2KWyJ7yeBUVvI+8G/wcAnimaTbkH0p9bbu39npDt76 o9rjvmBpeuHgtvanX24OyaVyDevZROgvlxJOvprp3z7KAkMRh4MrXI0PMC+PU+lVB432 CyGMf1Ij2VrZJj65nkzsDGNX4PbkfKM41VCfpVZugr8IBLLqM77tnrqJBPi4SHkRJhQn nYTA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=KQX1+fwLRww0qPIq6y9XkUyARq6GhdiqbQnB3Npgv2Y=; b=h3f8RF/qx52x0wqA8M4UXu+x3Pm91KHeguzePKiNuSMXi4FE/5R8JTkBGcirNlj0S/ 1hw/xvJtIS4d+PIZE+bRp5MHAT9wcqIUeQ9+NQcS1lVNgGjRBRO5U/NvXU31E6z539uJ dzqmojPUCOHD2LSoMP6gRP9qzpffJQ1cc/JGNRP9Z7lviLtschzq1+OeFuE2fp1o79C1 u59IhEvJNYV0M45nHER2+slW2YChBtXzISmwOjbVs/MZ+9XYy527HBKqpC1UimoziM7+ an/7oxTMrDMH5R9M43jGh07eixI2AzY5t9HhTTW8IsJk7z0Uazcu93CgPgp77Mc99wCa i/LQ== X-Gm-Message-State: AFeK/H3x2ijb7zGghd7fBPmV1a08LGkxOus5GNGPnNXXWj3sA/Bd0WkL18J/us6Je1nW8Q== X-Received: by 10.36.43.194 with SMTP id h185mr1263768ita.121.1490921581899; Thu, 30 Mar 2017 17:53:01 -0700 (PDT) Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id j4sm449428ita.29.2017.03.30.17.53.00 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 30 Mar 2017 17:53:01 -0700 (PDT) From: npostavs@users.sourceforge.net References: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> <87o9wq0wwz.fsf@users.sourceforge.net> Date: Thu, 30 Mar 2017 20:54:23 -0400 In-Reply-To: <87o9wq0wwz.fsf@users.sourceforge.net> (npostavs@users.sourceforge.net's message of "Sat, 25 Mar 2017 01:04:28 -0400") Message-ID: <871ste2rls.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.7 (/) 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