commit: 401ad3ebcf88837618fa559c5cea7666a4b30435 Author: Michael Orlitzky <mjo <AT> gentoo <DOT> org> AuthorDate: Thu Apr 25 00:39:30 2019 +0000 Commit: Michael Orlitzky <mjo <AT> gentoo <DOT> org> CommitDate: Fri Nov 22 13:31:16 2019 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=401ad3eb
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 <AT> gmail.com> Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org> function-reference/install-functions/text.xml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml index 2b0cbf2..06bc241 100644 --- 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,15 @@ 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. This is accomplished by installing a hidden file + prefixed with <c>.keep</c> to the directory in question. </ti> </tr> <tr>
