[gentoo-portage-dev] [PATCH v2 1/2] man/ebuild.5: document that dodir is for nonempty directories.
---
man/ebuild.5 | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/man/ebuild.5 b/man/ebuild.5
index 42a0599fe..28e9582d1 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -1271,7 +1271,8 @@ Creates directories inside of ${ED}.
.br
.BR 'dodir\ /usr/lib/apache'
creates ${ED}/usr/lib/apache. Note that the do* functions will run
-\fBdodir\fR for you.
+\fBdodir\fR for you. If this directory will be empty when it is merged,
+then please use \fBkeepdir\fR instead.
.TP
.B diropts\fR \fI[options for install(1)]
Can be used to define options for the install function used in
--
2.13.6
[gentoo-portage-dev] [PATCH v2 0/2] man page updates to promote keepdir usage
The main barrier to proper keepdir usage is that nobody knows what it's for. These two commits update the ebuild (5) man page with an explanation, namely that empty directories are undefined by the PMS. v2 uses different wording for dodir, and tries to be more precise about what we mean by "is (non)empty." Michael Orlitzky (2): man/ebuild.5: document that dodir is for nonempty directories. man/ebuild.5: document the rationale for using keepdir over dodir. man/ebuild.5 | 8 +--- 1 file changed, 5 insertions(+), 3 deletions(-) -- 2.13.6
[gentoo-portage-dev] [PATCH v2 2/2] man/ebuild.5: document the rationale for using keepdir over dodir.
--- man/ebuild.5 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/man/ebuild.5 b/man/ebuild.5 index 28e9582d1..8784a14ee 100644 --- a/man/ebuild.5 +++ b/man/ebuild.5 @@ -1285,8 +1285,9 @@ Sets the root (\fIDESTTREE\fR) for other functions like \fBdobin\fR, The default root is /usr. .TP .B keepdir\fR \fI [more paths] -Tells portage to leave directories behind even if they're empty. Functions -the same as \fBdodir\fR. +Similar to \fBdodir\fR, but used to create directories that would otherwise +be empty. The treatment of completely-empty directories is undefined by the +PMS, and using \fBkeepdir\fR ensures that they are tracked. .TP .B dobin\fR \fI [list of more binaries] Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/bin. -- 2.13.6
Re: [gentoo-portage-dev] [PATCH 2/2] man/ebuild.5: document the rationale for using keepdir over dodir.
On Fri, Jan 12, 2018 at 12:57 PM, Michael Orlitzky wrote: > --- > man/ebuild.5 | 5 +++-- > 1 file changed, 3 insertions(+), 2 deletions(-) > > diff --git a/man/ebuild.5 b/man/ebuild.5 > index 9dd969b03..5e2fdbcf5 100644 > --- a/man/ebuild.5 > +++ b/man/ebuild.5 > @@ -1285,8 +1285,9 @@ Sets the root (\fIDESTTREE\fR) for other functions like > \fBdobin\fR, > The default root is /usr. > .TP > .B keepdir\fR \fI [more paths] > -Tells portage to leave directories behind even if they're empty. Functions > -the same as \fBdodir\fR. > +Similar to \fBdodir\fR, but used to create directories that would otherwise > +be empty. The treatment of completely-empty directories is undefined by the > +PMS, and using \fBkeepdir\fR ensures that they are tracked. > .TP > .B dobin\fR \fI [list of more binaries] > Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/bin. This change looks ok to me.
Re: [gentoo-portage-dev] [PATCH 1/2] man/ebuild.5: document that dodir is for nonempty directories.
On Fri, Jan 12, 2018 at 12:57 PM, Michael Orlitzky wrote:
> ---
> man/ebuild.5 | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/man/ebuild.5 b/man/ebuild.5
> index 42a0599fe..9dd969b03 100644
> --- a/man/ebuild.5
> +++ b/man/ebuild.5
> @@ -1267,11 +1267,12 @@ that this expression does \fBNOT\fR use the offset
> prefix.
> runs sed on ${ED}/usr/bin/some\-script
> .TP
> .B dodir\fR \fI [more paths]
> -Creates directories inside of ${ED}.
> +Creates (nonempty) directories inside of ${ED}.
To me, this implies that the directory will be nonempty after calling dodir.
> .br
> .BR 'dodir\ /usr/lib/apache'
> creates ${ED}/usr/lib/apache. Note that the do* functions will run
> -\fBdodir\fR for you.
> +\fBdodir\fR for you. Empty directories must be created with \fBkeepdir\fR
> +instead.
Maybe rephrase this. For example:
To install a directory without any files, use keepdir instead.
[gentoo-portage-dev] [PATCH 0/2] man page updates to promote keepdir usage
The main barrier to proper keepdir usage is that nobody knows what it's for. These two commits update the ebuild (5) man page with an explanation, namely that empty directories are undefined by the PMS. Michael Orlitzky (2): man/ebuild.5: document that dodir is for nonempty directories. man/ebuild.5: document the rationale for using keepdir over dodir. man/ebuild.5 | 10 ++ 1 file changed, 6 insertions(+), 4 deletions(-) -- 2.13.6
[gentoo-portage-dev] [PATCH 2/2] man/ebuild.5: document the rationale for using keepdir over dodir.
--- man/ebuild.5 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/man/ebuild.5 b/man/ebuild.5 index 9dd969b03..5e2fdbcf5 100644 --- a/man/ebuild.5 +++ b/man/ebuild.5 @@ -1285,8 +1285,9 @@ Sets the root (\fIDESTTREE\fR) for other functions like \fBdobin\fR, The default root is /usr. .TP .B keepdir\fR \fI [more paths] -Tells portage to leave directories behind even if they're empty. Functions -the same as \fBdodir\fR. +Similar to \fBdodir\fR, but used to create directories that would otherwise +be empty. The treatment of completely-empty directories is undefined by the +PMS, and using \fBkeepdir\fR ensures that they are tracked. .TP .B dobin\fR \fI [list of more binaries] Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/bin. -- 2.13.6
[gentoo-portage-dev] [PATCH 1/2] man/ebuild.5: document that dodir is for nonempty directories.
---
man/ebuild.5 | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/man/ebuild.5 b/man/ebuild.5
index 42a0599fe..9dd969b03 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -1267,11 +1267,12 @@ that this expression does \fBNOT\fR use the offset
prefix.
runs sed on ${ED}/usr/bin/some\-script
.TP
.B dodir\fR \fI [more paths]
-Creates directories inside of ${ED}.
+Creates (nonempty) directories inside of ${ED}.
.br
.BR 'dodir\ /usr/lib/apache'
creates ${ED}/usr/lib/apache. Note that the do* functions will run
-\fBdodir\fR for you.
+\fBdodir\fR for you. Empty directories must be created with \fBkeepdir\fR
+instead.
.TP
.B diropts\fR \fI[options for install(1)]
Can be used to define options for the install function used in
--
2.13.6
