[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: How to install doxygen-generated HTML documentation?
From: |
Stepan Kasal |
Subject: |
Re: How to install doxygen-generated HTML documentation? |
Date: |
Wed, 14 May 2008 17:11:09 +0200 |
User-agent: |
Mutt/1.5.17 (2007-11-01) |
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
- How to install doxygen-generated HTML documentation?, Peter Simons, 2008/05/02
- Re: How to install doxygen-generated HTML documentation?, Warren Young, 2008/05/02
- Re: How to install doxygen-generated HTML documentation?, Peter Simons, 2008/05/02
- Re: How to install doxygen-generated HTML documentation?, Stepan Kasal, 2008/05/05
- Re: How to install doxygen-generated HTML documentation?, Peter Simons, 2008/05/05
- Re: How to install doxygen-generated HTML documentation?, Stepan Kasal, 2008/05/13
- Re: How to install doxygen-generated HTML documentation?, Peter Simons, 2008/05/13
- Re: How to install doxygen-generated HTML documentation?,
Stepan Kasal <=
- Re: How to install doxygen-generated HTML documentation?, Peter Simons, 2008/05/18