docs: do not set HTML install tree to 0755 perms

[jsquyres]

Follow-on to 8ffe33f: do not set the dirs in the installed HTML
files tree to have 0755 permissions because Automake doesn't do that
when it creates directories. Instead, use "find ..." to find all
directories and files in the generated _built/html tree and use the
Automake-provided installer macros to create the target directories
and install the target files with desireable permissions.

Additionally, add a comment explaining why the install-data-hook rule
exists, and why we are doing what we are doing in it.

Signed-off-by: Jeff Squyres [email protected]

To be added to #10255 when done.

[ibm-ompi]

The IBM CI (GNU/Scale) build failed! Please review the log, linked below.

Gist: https://gist.github.com/5f9117ae7324f71bd3162ad59e99d136

[ibm-ompi]

The IBM CI (XL) build failed! Please review the log, linked below.

Gist: https://gist.github.com/2b54fb084c71106c2656f34c39beb778

[ibm-ompi]

The IBM CI (PGI) build failed! Please review the log, linked below.

Gist: https://gist.github.com/acb9b4084be442a76e615b982cff50cf

[bwbarrett]

The error in distcheck looks real, although I'm not entirely sure I understand why those files were readonly to begin with.

[jsquyres]

@bwbarrett Blah. This is what's happening:

1. The generated man pages and HTML files are in the source tree (because it's doing a build of a tarball, so the tarball contains the pre-built man pages and HTML files).
2. make distcheck does a chmod -R u-w $srcdir to make the source tree unwriteable
3. Then distcheck does a configure+make+make install, which ends up doing cp -r $(srcdir)/_build/html $(DESTDIR)$(docdir) in the build tree docs dir

There's actually two problems here:

1. The source tree docs/_build/html (and all of its subdirs) are r-xr-xr-x. When we cp -r SRC TARGET, even without the -p option, with a umask of 22, it ends up copying those permissions. For example:

   $ umask
   022
   $ mkdir src_tree
   $ touch src_tree/a-file
   $ chmod -R u-w src_tree
   $ ls -la src_tree 
   total 0
   dr-xr-xr-x. 2 jsquyres jsquyres 20 Apr 12 07:20 ./
   drwxr-xr-x. 4 jsquyres jsquyres 52 Apr 12 07:20 ../
   -r--r--r--. 1 jsquyres jsquyres  0 Apr 12 07:20 a-file
   $ cp -r src_tree dest_tree
   $ ls -la dest_tree 
   total 0
   dr-xr-xr-x. 2 jsquyres jsquyres 20 Apr 12 07:20 ./
   drwxr-xr-x. 5 jsquyres jsquyres 69 Apr 12 07:20 ../
   -r--r--r--. 1 jsquyres jsquyres  0 Apr 12 07:20 a-file
   

   Hence, when make uninstall invokes rm -rf THE_INSTALLED_DOCS_HTML_TREE, we get the permission denied errors.

   Since we're removing the entire tree anyway, probably the easiest fix here would be to add a chmod -R a+w THE_INSTALLED_DOCS_HTML_TREE before the rm -rf in the uninstall-hook rule.

   Sound right to you?

2. The cp -r $(srcdir)/_build/html $(DESTDIR)$(docdir) action in the install-data-hook rule does the Wrong Thing when you're doing a VPATH build from a git clone (because the generated html tree is not in the source tree -- it's in the build tree). This doesn't show up in our testing because we only invoke distcheck, and in all of those cases, the generated HTML files are in the tarball/source tree; it only occurred to me to test this this morning when thinking through the above issues.

   I'll investigate what the Right Thing should be shortly.

[bwbarrett]

Instead of chmoding around, why not replace the cp -r with a find -type f -exec $(install_sh) -c -m 644?

[jsquyres]

@bwbarrett Done.

[bwbarrett]

bot:aws:retest