automake
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: advice for pre-generating documentation


From: Gaetan Nadon
Subject: Re: advice for pre-generating documentation
Date: Thu, 11 Feb 2010 15:44:02 -0500

On Thu, 2010-02-11 at 18:06 +0100, Andreas Jellinghaus wrote:

> Ah, thanks. I didn't know about EXTRA_DIST.
> 
> Is there some mechanism I can put a wildcard into automake
> files? for example it would be easier to specify "*.html",
> as the script downloads all wiki pages, and thus new pages
> would be added automaticaly that way.

Automake does not support or recommend wildcards:
http://www.gnu.org/software/automake/manual/automake.html#Wildcards


> 
> also I wonder:
> what about builddir vs. sourcedir? how do you handle that?

I am not usre I understand the question and I am not the one who
originally wrote the makefile for doxygen, here is an example of a
doxygen file target:

        $(builddir)/doxygen.head:
                $(LN_S) $(srcdir)/doxygen.head $@

You need to test by doing a VPATH build (where the build directory is
not the source directory. This is how 'make distcheck' builds. It will
be easy to debug in a VPATH build.
http://www.gnu.org/software/automake/manual/automake.html#VPATH-Builds


> if people have a tar.gz with pre-build documentation, it
> is in sourcedir. if people checkout svn and build in a seperate
> build root, the documentation is created in builddir.
> 

That's correct, if one choose to do a VPATH build.

> does automake handle that automaticaly?

I don't think there is anything for Automake to handle. The docs may be
different as the source code in the repo may not be the same as the one
in the tarball. Using a tarball as the seed for development source and
then downloading some or all of the code from svn is a development task.
It's one of n ways of getting source and building. 

> 
> and is there a nice way to remove the documentation 
> with "make clean" or "make distclean" if it was generated,
> but not remove it if it comes from the tar.gz?
> use the same if/else/endif around the CLEANFILES settings?
> 

Automake does not know whether you are working from a tarball or from a
repo. Opinions will vary on this, but this is what we do:

make clean: does the usual, but does not remove gen docs. The reason is
that the tarball builder may not have doxygen to re-create. He wanted to
clean the object code, not the docs!

make maintainer-clean: does the clean, plus it invokes our
maintainer-clean-local target and any file listed in the
MAINTAINRECLEANFILES variable. This target was designed by Automake for
situations like this where the builder may not have the tools to
re-create some generated files. So the doxygen generated files get
removed.

This is the comment that it will issue:

        @echo "This command is intended for maintainers to use"
        @echo "it deletes files that may require special tools to rebuild."

The answer is yes, there is a nice way to remove the docs: make
'maintainer-clean'. And yes, there is a nice way to clean all objects
code without removing the docs: 'make clean'. Whether the docs came from
a tarball, svn or hand dropped on the disk is irrelevant and there is no
way to know. 

The hard part is not the coding of the makefile but deciding on how it
should work for the user. The way it works for one project may not be
ideal for another one. 


> Thanks!
> 
> Regards, Andreas
> 
> 

Attachment: signature.asc
Description: This is a digitally signed message part


reply via email to

[Prev in Thread] Current Thread [Next in Thread]