http://fedoraproject.org/wiki/Packaging/Guidelines#DuplicateFiles:
A Fedora package must not contain any duplicate files in the %files listing.
What exactly does that refer to?
Only the rpmbuild "warning: File listed twice ..."? Or actual files included in multiple %files sections for (sub-)packages?
The latter is not detected by rpmbuild.
Michael Schwendt wrote:
http://fedoraproject.org/wiki/Packaging/Guidelines#DuplicateFiles:
A Fedora package must not contain any duplicate files in the %files listing.
What exactly does that refer to?
Only the rpmbuild "warning: File listed twice ..."? Or actual files included in multiple %files sections for (sub-)packages?
The latter is not detected by rpmbuild.
I'm not quite sure of the scope of the question or of the answer. My interpretation is that this is for a single file listed in the %file(s) section of a package and its sub-packages more than once.
Files duplicated between distinct SRPM's would be part of the Conflicts Guideline instead.
-Toshio
On Fri, 13 Feb 2009 10:14:37 -0800, Toshio wrote:
http://fedoraproject.org/wiki/Packaging/Guidelines#DuplicateFiles:
A Fedora package must not contain any duplicate files in the %files listing.
What exactly does that refer to?
Only the rpmbuild "warning: File listed twice ..."? Or actual files included in multiple %files sections for (sub-)packages?
The latter is not detected by rpmbuild.
I'm not quite sure of the scope of the question or of the answer.
Let me rephrase then for another try:
What are packagers and reviewers supposed to check in order to satisfy above guideline?
rpmbuild prints a warning for files/dirs which are listed more than once in _the same_ %files section.
However, rpmbuild does not notice if files/dirs are listed _in multiple_ %files sections. Not even %doc files.
Conclusively, only paying attention to rpmbuild's warnings is easy (a SHOULD guideline would suffice), but doesn't yield much. It only helps with subsequent packaging mistakes (such as moving one %files entry to another subpackage while keeping the duplicated entry in the old package).
That does not cover the worse case, i.e. because files duplicated in multiple %files sections are not detected by rpmbuild => the reviewer must examine package contents (with rpmls e.g.) manually.
[There's even a third case: Programs that load and display documentation files. Then, files included via %doc are also installed and expected in different directories. Packager should not simply remove duplicated files without verifying that the documentation can still be displayed from within the program.]
My interpretation is that this is for a single file listed in the %file(s) section of a package and its sub-packages more than once.
That would be both cases I cover above.
Any suggestion for a better wording of the current guideline? In particular, it refers to "the %files listing" (singular!) and not all %files listings [including subpackages].
Files duplicated between distinct SRPM's would be part of the Conflicts Guideline instead.
Yes, that's something else.
Michael Schwendt wrote:
On Fri, 13 Feb 2009 10:14:37 -0800, Toshio wrote:
http://fedoraproject.org/wiki/Packaging/Guidelines#DuplicateFiles:
A Fedora package must not contain any duplicate files in the %files listing.
What exactly does that refer to?
Only the rpmbuild "warning: File listed twice ..."? Or actual files included in multiple %files sections for (sub-)packages?
The latter is not detected by rpmbuild.
I'm not quite sure of the scope of the question or of the answer.
Let me rephrase then for another try:
What are packagers and reviewers supposed to check in order to satisfy above guideline?
rpmbuild prints a warning for files/dirs which are listed more than once in _the same_ %files section.
However, rpmbuild does not notice if files/dirs are listed _in multiple_ %files sections. Not even %doc files.
Conclusively, only paying attention to rpmbuild's warnings is easy (a SHOULD guideline would suffice), but doesn't yield much. It only helps with subsequent packaging mistakes (such as moving one %files entry to another subpackage while keeping the duplicated entry in the old package).
That does not cover the worse case, i.e. because files duplicated in multiple %files sections are not detected by rpmbuild => the reviewer must examine package contents (with rpmls e.g.) manually.
[There's even a third case: Programs that load and display documentation files. Then, files included via %doc are also installed and expected in different directories. Packager should not simply remove duplicated files without verifying that the documentation can still be displayed from within the program.]
My interpretation is that this is for a single file listed in the %file(s) section of a package and its sub-packages more than once.
That would be both cases I cover above.
Any suggestion for a better wording of the current guideline? In particular, it refers to "the %files listing" (singular!) and not all %files listings [including subpackages].
How about:
""" A Fedora package must not list a file more than once in the spec file's %files listings. """
-Toshio
On Saturday 14 February 2009, Toshio Kuratomi wrote:
""" A Fedora package must not list a file more than once in the spec file's %files listings. """
This would mean that tiny -common subpackages containing for example only "%doc README COPYING" and perhaps a common base dir and/or a common config file would have to be always created if a specfile creates two otherwise independent binary packages. Is that really always desirable?
Ville Skyttä wrote:
On Saturday 14 February 2009, Toshio Kuratomi wrote:
""" A Fedora package must not list a file more than once in the spec file's %files listings. """
This would mean that tiny -common subpackages containing for example only "%doc README COPYING" and perhaps a common base dir and/or a common config file would have to be always created if a specfile creates two otherwise independent binary packages. Is that really always desirable?
That's undesirable but is that what it means? I see a lot of cases where we ship with README, COPYING, etc in one of a set of package+subpackages and the other subpackages contain no documentation.
-Toshio
On Sat, 14 Feb 2009 23:38:18 +0200, Ville wrote:
On Saturday 14 February 2009, Toshio Kuratomi wrote:
""" A Fedora package must not list a file more than once in the spec file's %files listings. """
This would mean that tiny -common subpackages containing for example only "%doc README COPYING" and perhaps a common base dir and/or a common config file would have to be always created if a specfile creates two otherwise independent binary packages. Is that really always desirable?
For a MUST item in the guidelines, it is much too short and vague. How about:
In a Fedora package .spec file, any of the files/dirs installed in the buildroot must not be included in the package(s) %files lists more than once. Unless there is good reason, and in that case there ought to be a comment in the .spec file.
Michael Schwendt wrote:
On Sat, 14 Feb 2009 23:38:18 +0200, Ville wrote:
On Saturday 14 February 2009, Toshio Kuratomi wrote:
""" A Fedora package must not list a file more than once in the spec file's %files listings. """
This would mean that tiny -common subpackages containing for example only "%doc README COPYING" and perhaps a common base dir and/or a common config file would have to be always created if a specfile creates two otherwise independent binary packages. Is that really always desirable?
For a MUST item in the guidelines, it is much too short and vague. How about:
In a Fedora package .spec file, any of the files/dirs installed in the buildroot must not be included in the package(s) %files lists more than once. Unless there is good reason, and in that case there ought to be a comment in the .spec file.
What's an example of a good reason?
(For instance, I want to know if including README/COPYING in multiple subpackages is best practice or should be frowned upon).
-Toshio
On Sun, 15 Feb 2009 10:59:30 -0800, Toshio wrote:
How about:
In a Fedora package .spec file, any of the files/dirs installed in the buildroot must not be included in the package(s) %files lists more than once. Unless there is good reason, and in that case there ought to be a comment in the .spec file.What's an example of a good reason?
A comment in the spec files which explains _why_ the files are duplicated. ;-)
(For instance, I want to know if including README/COPYING in multiple subpackages is best practice or should be frowned upon).
Can you point to a package that does that? Perhaps examining specific pkgs would help?
If it shall be possible to install the subpackages individually and separate from eachother, that may be reason enough to include such %doc files in each pkg as a matter of convenience for the user [and as not to create a -common pkg for just a few files]. Same applies to directories, as not to create a -common pkg just for directory ownership. In general, it may even be applicable to scripts and binaries shared by separately installable subpackages.
If it's a lib pkg that includes the docs a 2nd time in the -devel pkg, that would be bad. In particular because usually the -devel pkg requires the main lib pkg -- and because our placement of %doc files is broken. Every subpackage creates its own docdir, which means that a lib and its -devel pkg put their %doc files into two docdirs.
Or not a good reason would be if a packager duplicates files in subpkgs just to make rpmlint ("No documentation") happy.
Michael Schwendt wrote:
On Sun, 15 Feb 2009 10:59:30 -0800, Toshio wrote:
How about:
In a Fedora package .spec file, any of the files/dirs installed in the buildroot must not be included in the package(s) %files lists more than once. Unless there is good reason, and in that case there ought to be a comment in the .spec file.What's an example of a good reason?
A comment in the spec files which explains _why_ the files are duplicated. ;-)
I mean, what are examples when packagers should include files or directories in two %files sections for separate subpackages.
(For instance, I want to know if including README/COPYING in multiple subpackages is best practice or should be frowned upon).
Can you point to a package that does that? Perhaps examining specific pkgs would help?
Nope. Villa said this would be a reason that packagers would have to resort to a separate subpackage for the docs. I'm sort of questioning whether this ever comes up in practice.
If it shall be possible to install the subpackages individually and separate from eachother, that may be reason enough to include such %doc files in each pkg as a matter of convenience for the user [and as not to create a -common pkg for just a few files]. Same applies to directories, as not to create a -common pkg just for directory ownership. In general, it may even be applicable to scripts and binaries shared by separately installable subpackages.
Do we have examples of where this is a problem? Most subpackages would depend on their main package and that package could create the directories needed by the independent parts. I understand the theory here but I'd like to see some examples of where this is a real-life problem so we can point people at it.
This has gone from a clarification of wording to downgrading a MUST to a SHOULD. I'd like to understand what problems we're solving by doing that so we can write better Guidance of when it's appropriate and not appropriate to duplicate files in different sections. Otherwise people who just want to check off review items aren't going to understand when it's sufficient to merely comment something out of the ordinary and when the out-of-the-ordinary should be changed.
If it's a lib pkg that includes the docs a 2nd time in the -devel pkg, that would be bad. In particular because usually the -devel pkg requires the main lib pkg -- and because our placement of %doc files is broken. Every subpackage creates its own docdir, which means that a lib and its -devel pkg put their %doc files into two docdirs.
Or not a good reason would be if a packager duplicates files in subpkgs just to make rpmlint ("No documentation") happy.
Yep, agreed on both counts that a package that does this should be corrected instead of being commented and passed through review.
-Toshio
On Sun, 15 Feb 2009 13:55:09 -0800, Toshio wrote:
I mean, what are examples when packagers should include files or directories in two %files sections for separate subpackages.
No -common pkg, no shared main pkg, but multiple subpackages which may be installed independently. Imagine plugin pkgs: one for MySQL, another one for Postgresql, even another one for SQLite ... you may want to put %doc files into each subpkg.
One can expand that line of thinking and also duplicate directories and other types of files in each subpkg -- and consider a common pkg only if the gain would be big enough.
Whether packages SHOULD duplicate files/dirs or MAY do it, is another question. According to the current guideline it MUST NOT be done.
Concerning %doc license texts, the ReviewGuidelines are not clear enough with regard to subpkgs.
This has gone from a clarification of wording to downgrading a MUST to a SHOULD.
Sure. A guideline that is not understood cannot really be mandatory, unless we follow such guidelines blindly nowadays. Hence we're reviewing this guideline, and if nobody raises a hand and gives an explanation, it's better to modify the guideline until examples are shown.
Otherwise people who just want to check off review items aren't going to understand when it's sufficient to merely comment something out of the ordinary and when the out-of-the-ordinary should be changed.
How do they process this review item currently?
IMO, they simply tick off the item like an annoying checkbox without really performing any tests related to "rpmls/rpm -qlvp". Or they only watch for rpmbuild's lame warnings. Unowned directories and entire trees (not just below %datadir) included in multiple subpkgs are evidence of that.
With my reduced reviewing activity, I still run into packagers, who are not familiar with their %files lists or who run into packaging pitfalls related to %files lists.
Le Lun 16 février 2009 10:08, Michael Schwendt a écrit :
On Sun, 15 Feb 2009 13:55:09 -0800, Toshio wrote:
I mean, what are examples when packagers should include files or directories in two %files sections for separate subpackages.
No -common pkg, no shared main pkg, but multiple subpackages which may be installed independently. Imagine plugin pkgs: one for MySQL, another one for Postgresql, even another one for SQLite ... you may want to put %doc files into each subpkg.
However, the problem with "MAY" is that it's very difficult to document simply and complex guidelines are guidelines no one understands or follows.
For better or worse multi-font packages use the -common model. It's probably massively overkill when -common just has one .txt file in it (plus a dir, plus correct deps), but every single attempt on my part to document "MAY" resulted in problems for the unwary packager or reviewer (in some cases, rather embarrassingly, me included).
So my target now is to have subpackages as simple as possible, dep complexity in -common, and too bad if -common is tiny in many cases. It's better than spread dep complexity over many subpackages and have to explain releng why a big pdf/doc documentation file is duplicated many times over.
packaging@lists.fedoraproject.org
-
Michael Schwendt -
Nicolas Mailhot -
Toshio Kuratomi -
Ville Skyttä