GNU bug report logs - #40699
"dist Hook" documentation in manual is incorrect or unclear about write permissions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 40699 in the body.
You can then email your comments to 40699 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Vincent Lefevre <vincent <at> vinc17.net>
To: bug-automake <at> gnu.org
Subject: "dist Hook" documentation in manual is incorrect or unclear about
 write permissions
Date: Sat, 18 Apr 2020 19:12:12 +0200

doc/automake.texi contains:

------------------------------------------------------------------------
@example
EXTRA_DIST = doc
dist-hook:
        rm -rf `find $(distdir)/doc -type d -name .svn`
@end example

@c The caveats described here should be documented in 'disthook.sh'.
@noindent
Note that the @code{dist-hook} recipe shouldn't assume that the regular
files in the distribution directory are writable; this might not be the
case if one is packaging from a read-only source tree, or when a
@code{make distcheck} is being done.  For similar reasons, the recipe
shouldn't assume that the subdirectories put into the distribution
directory as an effect of having them listed in @code{EXTRA_DIST} are
writable.  So, if the @code{dist-hook} recipe wants to modify the
content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
distribution directory, it should explicitly to make it writable first:

@example
EXTRA_DIST = README doc
dist-hook:
        chmod u+w $(distdir)/README $(distdir)/doc
        echo "Distribution date: `date`" >> README
        rm -f $(distdir)/doc/HACKING
@end example
------------------------------------------------------------------------

So, if the subdirectories may not be writable, how can the rm in the
first example work without changing the permissions first?

-- 
Vincent Lefèvre <vincent <at> vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Message #8 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: vincent <at> vinc17.net
Cc: 40699 <at> debbugs.gnu.org
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Sat, 18 Apr 2020 15:04:08 -0600

Hi Vincent,

    So, if the subdirectories may not be writable, how can the rm in the
    first example work without changing the permissions first?

    [namely:]
    dist-hook:
            rm -rf `find $(distdir)/doc -type d -name .svn`

That example belongs to the preceding paragraph 
  (Occasionally it is useful to be able to change the distribution ...)
not the following paragraph that you quoted.

Also, not that I wrote any of this, but it seems to me that the
pervasive assumption is that the automake user in fact owns the file
trees in question. Thus rm -rf should work even if it's mode zero.
Of course it won't work on a read-only source tree, but, well, it's just
an example ... --thanks, karl.

Message #11 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Vincent Lefevre <vincent <at> vinc17.net>
To: Karl Berry <karl <at> freefriends.org>
Cc: 40699 <at> debbugs.gnu.org
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Sun, 19 Apr 2020 00:02:09 +0200

On 2020-04-18 15:04:08 -0600, Karl Berry wrote:
> Hi Vincent,
> 
>     So, if the subdirectories may not be writable, how can the rm in the
>     first example work without changing the permissions first?
> 
>     [namely:]
>     dist-hook:
>             rm -rf `find $(distdir)/doc -type d -name .svn`
> 
> That example belongs to the preceding paragraph 
>   (Occasionally it is useful to be able to change the distribution ...)
> not the following paragraph that you quoted.

I know, but the paragraph that follows shows an issue with this
example.

> Also, not that I wrote any of this, but it seems to me that the
> pervasive assumption is that the automake user in fact owns the file
> trees in question. Thus rm -rf should work even if it's mode zero.

No, it doesn't. At least not with

  rm (GNU coreutils) 8.30

i.e. it does not change the permissions in order to make the removal
work recursively (the -f just means that it ignores nonexistent files
and that it will never prompt for confirmation).

> Of course it won't work on a read-only source tree, but, well, it's just
> an example ... --thanks, karl.

It's just an example, but it should be correct (at least if there are
no warnings about things that have been dropped to make it simpler).
A user may want to copy-paste this example, and he will get something
incorrect.

-- 
Vincent Lefèvre <vincent <at> vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Message #14 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Nick Bowler <nbowler <at> draconx.ca>
To: Vincent Lefevre <vincent <at> vinc17.net>
Cc: 40699 <at> debbugs.gnu.org, Karl Berry <karl <at> freefriends.org>
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Sat, 18 Apr 2020 19:11:14 -0400

On 18/04/2020, Vincent Lefevre <vincent <at> vinc17.net> wrote:
> On 2020-04-18 15:04:08 -0600, Karl Berry wrote:
[...]
>> Also, not that I wrote any of this, but it seems to me that the
>> pervasive assumption is that the automake user in fact owns the file
>> trees in question. Thus rm -rf should work even if it's mode zero.
>
> No, it doesn't. At least not with
>
>   rm (GNU coreutils) 8.30
>
> i.e. it does not change the permissions in order to make the removal
> work recursively (the -f just means that it ignores nonexistent files
> and that it will never prompt for confirmation).
>
>> Of course it won't work on a read-only source tree, but, well, it's just
>> an example ... --thanks, karl.
>
> It's just an example, but it should be correct (at least if there are
> no warnings about things that have been dropped to make it simpler).
> A user may want to copy-paste this example, and he will get something
> incorrect.

I guess the note about dist-hooks when packaging from a read-only srcdir
was added because of my bug report[1].

I have never noticed read-only _directories_ in the distdir before (I
have assumed they are always created read-write so that Automake can
put distributed files in them) but I also don't ever put directory
names in EXTRA_DIST which is the case specifically called out in the
documentation.

I think it's kind of weird that distribution permissions can depend on
how the package tarball was unpacked so since then I always use
dist-hook to fix up permissions in $(distdir) before anything else.

[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10878

Cheers,
  Nick

Message #17 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Vincent Lefevre <vincent <at> vinc17.net>
To: Nick Bowler <nbowler <at> draconx.ca>
Cc: 40699 <at> debbugs.gnu.org, Karl Berry <karl <at> freefriends.org>
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Sun, 19 Apr 2020 02:37:59 +0200

On 2020-04-18 19:11:14 -0400, Nick Bowler wrote:
> I guess the note about dist-hooks when packaging from a read-only srcdir
> was added because of my bug report[1].
> 
> I have never noticed read-only _directories_ in the distdir before (I
> have assumed they are always created read-write so that Automake can
> put distributed files in them) but I also don't ever put directory
> names in EXTRA_DIST which is the case specifically called out in the
> documentation.
> 
> I think it's kind of weird that distribution permissions can depend on
> how the package tarball was unpacked so since then I always use
> dist-hook to fix up permissions in $(distdir) before anything else.
> 
> [1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10878

I can reproduce the issue with "make dist" and code like the example

     EXTRA_DIST = doc
     dist-hook:
             rm -rf `find $(distdir)/doc -type d -name .svn`

when the directory is read-only. But if the directory is not
read-only, "make distcheck" does not fail. So it seems that
"make distcheck" no longer tests "make dist" from a read-only
source tree (it tests the build from a read-only source tree,
but for "make dist", it first extracts the tarball in the
build directory then runs "make dist" from the new copy of
the source tree, which is not read-only).

-- 
Vincent Lefèvre <vincent <at> vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Message #20 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: vincent <at> vinc17.net
Cc: 40699 <at> debbugs.gnu.org
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Mon, 20 Apr 2020 14:59:00 -0600

    i.e. it does not change the permissions in order to make the removal
    work recursively

Right, I see it now. Had been testing the wrong thing.

So, can you propose a specific change for the manual? -k

Message #23 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Vincent Lefevre <vincent <at> vinc17.net>
To: Karl Berry <karl <at> freefriends.org>
Cc: 40699 <at> debbugs.gnu.org
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Thu, 23 Apr 2020 17:40:39 +0200

On 2020-04-20 14:59:00 -0600, Karl Berry wrote:
>     i.e. it does not change the permissions in order to make the removal
>     work recursively
> 
> Right, I see it now. Had been testing the wrong thing.
> 
> So, can you propose a specific change for the manual? -k

I think that it is sufficient to fix the example (the explanation
is just below). BTW, the second example is also incorrect.

commit a639e5b51cadbaff88ca4059b4db4571c811070c
Author: Vincent Lefevre <vincent <at> vinc17.net>
Date:   2020-04-23 17:33:54 +0200

    doc: fix dist-hook examples

diff --git a/doc/automake.texi b/doc/automake.texi
index 469a72971..1b35883b9 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8497,6 +8497,7 @@ a directory in @code{EXTRA_DIST}:
 @example
 EXTRA_DIST = doc
 dist-hook:
+        chmod -R u+w $(distdir)/doc
         rm -rf `find $(distdir)/doc -type d -name .svn`
 @end example
 
@@ -8516,7 +8517,7 @@ distribution directory, it should explicitly to make it writable first:
 EXTRA_DIST = README doc
 dist-hook:
         chmod u+w $(distdir)/README $(distdir)/doc
-        echo "Distribution date: `date`" >> README
+        echo "Distribution date: `date`" >> $(distdir)/README
         rm -f $(distdir)/doc/HACKING
 @end example
 

-- 
Vincent Lefèvre <vincent <at> vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Message #26 received at 40699 <at> debbugs.gnu.org (full text, mbox):

From: Karl Berry <karl <at> freefriends.org>
To: vincent <at> vinc17.net
Cc: 40699 <at> debbugs.gnu.org
Subject: Re: bug#40699: "dist Hook" documentation in manual is incorrect or
 unclear about write permissions
Date: Thu, 23 Apr 2020 18:59:10 -0600

    +        chmod -R u+w $(distdir)/doc
    ...
    -        echo "Distribution date: `date`" >> README
    +        echo "Distribution date: `date`" >> $(distdir)/README

Ok, pushed. Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.