The devmanual should have a better explanation of keepdir and dodir usage. I will be submitting a patch to the devmanual with a better explanation. Reproducible: Always
Created attachment 335266 [details, diff] install-functions.patch I welcome comments.
Looks good to me but I am not 100% sure about these functions. CC'ing pms
- Install a directory + Install a directory that can be removed by a package unmerge when any package that owns it + has been unmerged and it is empty. This misses the point. Per PMS section 12.2.2: "Ebuilds must not attempt to install an empty directory." <http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-15000012.2.2> From this it follows that the directory can only be empty when all packages have been unmerged. - Create a directory with an empty <c>.keep</c> file in it. + Install a directory, typically used to store configuration or generated runtime data, + that can be removed by a package unmerge only when all other + packages that own it have been unmerged and it is empty. PMS says (section 11.3.3.8): "Creates a directory as for dodir, and an empty file whose name starts with .keep in that directory to ensure that the directory does not get removed by the package manager should it be empty at any point." <http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-13600011.3.3.8> So, the important difference between the two commands is: - dodir is used for directories that are afterwards (in src_install) populated by files. - keepdir is used to create an otherwise empty directory, with a .keep* placeholder that prevents their removal.
(In reply to comment #3) > This misses the point. Per PMS section 12.2.2: > "Ebuilds must not attempt to install an empty directory." > <http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-15000012.2.2> > > From this it follows that the directory can only be empty when all packages > have been unmerged. If an ebuild must not create empty directories, then how do deal with a package that needs to store data in the directory during runtime but does not create the directory? How about an /etc directory where a configuration file could be added but is optional? > PMS says (section 11.3.3.8): > "Creates a directory as for dodir, and an empty file whose name starts with > .keep in that directory to ensure that the directory does not get removed by > the package manager should it be empty at any point." > <http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-13600011.3.3.8> > > So, the important difference between the two commands is: > - dodir is used for directories that are afterwards (in src_install) > populated by files. > - keepdir is used to create an otherwise empty directory, with a .keep* > placeholder that prevents their removal. By "keepdir is used to create an otherwise empty directory", you mean it's allowed to create an empty directory? Doesn't that directlly contradict your earlier statement regarding MS section 12.2.2? .keep* does not prevent the removal of the directory. I tested this. If it is empty or becomes empty (e.g. user deleted files in there but not the .keep* file), then unmerge will remove this directory assuming no other package claims it with another .keep* file in that directory. This still doesn't explain the difference between dodir and keepdir. The distinction between these two commands is closely tied to how they act on an unmerge. I removed the mention of the .keep* file because it's really irrelevant to the person writing the ebuild since they're more interested in the behavior of the command and not how portage internally deals with it.
I submitted a patch for "man 5 ebuild" a while ago that clarifies this in that man page. It might be worth stealing; basically it tacks on the additional information, dodir: ... If this directory will be empty when it is merged, then please use keepdir instead. keepdir: ... used to create directories that would otherwise be empty. The treatment of completely-empty directories is undefined by PMS, and using keepdir ensures that they are tracked.
(In reply to Michael Orlitzky from comment #5) > I submitted a patch for "man 5 ebuild" a while ago that clarifies this in > that man page. It might be worth stealing; basically it tacks on the > additional information, > > dodir: ... If this directory will be empty when it is merged, then > please use keepdir instead. > > keepdir: ... used to create directories that would otherwise be empty. > The treatment of completely-empty directories is undefined by > PMS, and using keepdir ensures that they are tracked. I like that the explanation directs the ebuild writer to keepdir in that situation. I would be happy with that in the devmanual.
Created attachment 574088 [details, diff] 0001-function-reference-install-functions-clarify-dodir-k.patch How's this?
That's a much better explanation than before. I'd be happy with that.
Created attachment 574328 [details, diff] 0001-function-reference-install-functions-clarify-dodir-k.patch This version adds nothing except my Signed-off-by line. Sorry, I'm new at this.
Ping: seven year old bug with a six-month old patch and no response.
(In reply to Michael Orlitzky from comment #9) > Created attachment 574328 [details, diff] [details, diff] > 0001-function-reference-install-functions-clarify-dodir-k.patch --- a/function-reference/install-functions/text.xml +++ b/function-reference/install-functions/text.xml @@ -117,7 +117,9 @@ the first is the source name, the second the name to use when installing. <c>dodir</c> </ti> <ti> - Install a directory + Install a directory that will be non-empty when the package is + merged. For directories that will be empty, please use + <c>keepdir</c> instead. </ti> </tr> <tr> @@ -288,9 +290,13 @@ the first is the source name, the second the name to use when installing. <c>keepdir</c> </ti> <ti> - Create a directory which will be preserved by the package - manager (This is typically accomplished by inserting an empty - <c>.keep_${CATEGORY}_${PN}-${SLOT%/*}</c> file in the directory) Please don't drop the information about the .keep* file. + Install a directory that will be empty when the package is + merged. This is like <c>dodir</c>, but for empty directories + instead. As of EAPI 7, <uri This applies in all EAPIs, so the mentioning of EAPI 7 is confusing. + link="https://projects.gentoo.org/pms/7/pms.html#x1-14200013.2.2">the Whitespace (but link should be dropped anyway). + handling of empty directories is undefined by the package + manager specification</uri>, and the <c>keepdir</c> function + exists to ensure that the (otherwise empty) directory is tracked. </ti> </tr> <tr>
Created attachment 597124 [details, diff] 0001-function-reference-install-functions-clarify-dodir-k.patch (In reply to Ulrich Müller from comment #11) > > Please don't drop the information about the .keep* file. > I've put back the mention of it, but without the word "typically" and without describing the exact naming scheme, since both of those are implementation details of only one package manager. Hopefully that is OK. > This applies in all EAPIs, so the mentioning of EAPI 7 is confusing. In general I think it's helpful to mention to which EAPIs our advice applies, because these pages consistently go 5+ years out-of-date and things change in new EAPIs. If we're on EAPI=10 and the page still says "7", then that's a good indication that the reader should verify what it says. But in this case, re-reading it after so long, I agree that mentioning it is confusing. I removed that phrase, but left the link to EAPI=7 which is still a decent hint should this page become outdated. > + link="https://projects.gentoo.org/pms/7/pms.html#x1-14200013.2.2">the > > Whitespace (but link should be dropped anyway). Why drop the link? It doesn't take any extra space, and points people to the piece of information that we're talking about. (The whitespace is what emacs's fill-paragraph does, and I'll change that to whatever you want, or you can edit it afterwards -- makes no difference to me.)
(In reply to Michael Orlitzky from comment #12) > Created attachment 597124 [details, diff] [details, diff] > 0001-function-reference-install-functions-clarify-dodir-k.patch @@ -288,9 +290,16 @@ the first is the source name, the second the name to use when installing. <c>keepdir</c> </ti> <ti> - Create a directory which will be preserved by the package - manager (This is typically accomplished by inserting an empty - <c>.keep_${CATEGORY}_${PN}-${SLOT%/*}</c> file in the directory) + Install a directory that will be empty when the package is + merged. This is like <c>dodir</c>, but for empty directories + instead. <uri + link="https://projects.gentoo.org/pms/7/pms.html#x1-14200013.2.2">The + handling of empty directories is undefined by the package + manager specification</uri>, and the <c>keepdir</c> function + exists to ensure that the (otherwise empty) directory is + tracked. Portage, for example, accomplishes this by installing a + hidden file prefixed with <c>.keep_</c> to the directory in + question. Just say that the filename begins with ".keep" which is what is defined by the spec, in which case there's no need to refer to Portage specific behaviour. (The underscore is indeed Portage specific, but I don't see what mentioning it would buy us here.) </ti> </tr> <tr>
Created attachment 597138 [details, diff] 0001-function-reference-install-functions-clarify-dodir-k.patch (In reply to Ulrich Müller from comment #13) > > Just say that the filename begins with ".keep" which is what is defined by > the spec, in which case there's no need to refer to Portage specific > behaviour. (The underscore is indeed Portage specific, but I don't see what > mentioning it would buy us here.) I had forgotten that the ".keep" prefix was in the PMS, if I ever knew it. Thanks for the pointer. I'm even happier with this version.
(In reply to Michael Orlitzky from comment #14) > Created attachment 597138 [details, diff] [details, diff] > 0001-function-reference-install-functions-clarify-dodir-k.patch LGTM (except for that ugly line break in the middle of a uri tag, but that's not a blocker ;)
The bug has been closed via the following commit(s): https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=401ad3ebcf88837618fa559c5cea7666a4b30435 commit 401ad3ebcf88837618fa559c5cea7666a4b30435 Author: Michael Orlitzky <mjo@gentoo.org> AuthorDate: 2019-04-25 00:39:30 +0000 Commit: Michael Orlitzky <mjo@gentoo.org> CommitDate: 2019-11-22 13:31:16 +0000 function-reference/install-functions: clarify dodir/keepdir usage. The existing "Install Functions Reference" documentation on dodir() and keepdir() is a bit wishy-washy. What developers really want to know is, when do I use one, and when do I use the other? This commit updates the descriptions of those two functions to provide that information. If the directory will be non-empty, dodir() is fine. Otherwise, keepdir() should be used. Some rationale for the existence of the keepdir() function is also provided for the skeptical developer who might otherwise find it superfluous. This change mirrors an update to the ebuild(5) man page in portage. Closes: https://bugs.gentoo.org/451472 Reported-by: Matthew Schultz <mattsch@gmail.com> Signed-off-by: Michael Orlitzky <mjo@gentoo.org> function-reference/install-functions/text.xml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-)
Thanks ulm.
