Re: How to install doxygen-generated HTML documentation?

[Stepan Kasal]

Hello,

On Tue, May 13, 2008 at 07:37:15PM +0200, Peter Simons wrote:
> The 'dist' and 'install' targets should work, but 'distcheck'
> fails with a "permission denied" error. If you can figure out how
> to remedy the problem, then that would be really great.

well.  First, I sucessfully reproduced the problem:

autoreconf -i && ./configure && make distcheck

fail.

Then I analyzed where it failed.  distcheck does this:
 - creates a tarball
 - unapcks it
 - flags the unpacked tree read-only
 - configures it in a subdirectory called _build
 - runs "make dist" there

So, basically, the problem is that for a vpath build with read-only
source tree, make dist does not work.  In practice, this is not a big
problem, so you can just ignore it.  (If you want to keep the
advantage of using distcheck, add a hack for this situation [1], or
mask this individual problem, see [2] below.)

>From a bit broader picture, this is a conflict between source dir and
build dir; perhaps it would be better to create the documentation in
the $(srcdir).  But again, if you re-create the docs each time dist
is called, you will have problems with running "make dist" with a
read-only source.  You can either use a stamp file to eliminate
unnecessary calls of doxygen (see also [3] below) or, again, use [1]
or [2].

Yet another way, not discussed so far, is to generate list of files
for Automake, eliminating the need for a directory in EXTRA_DIST.
See [4] below.

This is the outline of your options, hope it helps!

Now to the details:

[1] a hack.  Apply the patch Makefile.patch (attached to this mail).
It removes the duplicate files from the build tree, avoiding the
clash described above.  (When srcdir=builddir, the file is the same,
cmp succeeds, but you cannot delete it.  Instead of inventing a check
whether srcdir is the same as buildir, I used the trick with "test -w".)
With this modification, your tarball passes distcheck.

[2] You can avoid running your "html-local" within the distcheck.
You need to enclose that part of Makefile.am to "if ENABLE_DOXYGEN"
and add something like this to configure.ac:
AC_ARG_ENABLE([doxygen],
  [AS_HELP_STRING([--disable-doxygen],
    [disable doc generation])])
AM_CONDITIONAL([ENABLE_DOXYGEN], [test "x$enable_doxygen" != xno])
And then you can add
DISTCHECK_CONFIGURE_FLAGS = --disable-doxygen
to the (top-level) Makefile.am.

[3] The stamp file might be something like html/stamp, but perhaps
html/index.html might work.  Something which is touched each time the
docs are refreshed.  It would depend on all the source files which
contribute to the docs.  (Yes, that would be a long list, hard to
maintain.  Generating this list comes to mind, but then the question
is if it is woth it, perhaps [4] below is then easier.)

[4]
Another angle is to understand that Automake really wants to have a
complete list of distributed files, and it really is possible even in
this case.  This list of files is not convenient to maintain
manually, but you can generate a file doxygen_files.make containing:

doxygen_files = \
  html/index.html \
  html/this...html \
  html/that...html \
     .... [etc]
include doxygen_files.make

This include is processed by automake, so the list is pasted into the
generated Makefile.in.  You can then use $(doxygen_files) in
dist_pkgdata_DATA eliminating all the hacks discused in this thread.
But you have to be careful when defining the rule for
doxygen_files.make and for docs generation.  You need to avoid a
situation where documents, including doxygen_files.make, are rebuilt
even when they are up-to date, which could even get you to an
infinite loop.  I'm not able to work out an example here.

--- At the end a few comments about your Makefile.am.
Using $(builddir) does not make much sense, it's always "."

MAINTAINERCLEANFILES = configure etc.
Many people want a clean which would leave only the source files,
without autoconfigury.  Unfortunately, twisting maintainer-clean that
way is not compatible with GNU Coding Standards.  OTOH, users do not
use maintainer-clean, so you do not do much harm by breaching that
part of the standard.

Uff, rather lenthy mail, I hope at least some parts of ot will help
you.

Stepan Kasal

Makefile.patch
Description: Text document