Control: severity -1 important
Raising the severity due to the number of packages affected and the
number of workarounds deployed already.
On Sun, Jun 19, 2011 at 02:25:44PM +0100, Marcin Owsiany wrote:
> Here's my proposal:
>
> whenever doxygen is used during libgadu-doc build, it should:
>
> 1) install symlinks to /usr/share/javascript/jquery/jquery*.js rather
> than outputing the file contents
>
> 2) add misc:Depends=libjs-jquery to debian/libgadu-doc.substvars
I am attaching a preliminary version of dh_doxygen (bluntly copied from
Jakub Wilk's dh_sphinxdoc). In addition to the above it will also clean
*.md5 and *.map files used to speed up incremental regeneration (which
is useless in binary packages). Note that the substvar is called
${doxygen:Depends} instead. Also ${doxygen:Built-Using} is provided to
meet recent policy changes.
Open issues:
* Maybe the libjs-jquery dependency should be versioned?
* Would it be possible for doxygen to ship a doxygen-common package
shipping files like doxygen.css doxygen.png tabs.css dynsections.js?
That way we might be able to get rid of the Built-Using field.
Helmut
#!/usr/bin/perl
# Copyright © 2011 Jakub Wilk <[email protected]>
# Copyright © 2013 Helmut Grohne <[email protected]>
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
=head1 NAME
dh_doxygen - helps with packaging doxygen-generated documentation
=head1 SYNOPSIS
dh_doxygen [S<I<debhelper options>>] [B<-X>I<item>] [I<directory>...]
=head1 DESCRIPTION
B<dh_doxygen> is a debhelper program that prepares doxygen-generated
documentation for inclusion in a Debian package. More specifically:
=over 4
=item *
It replaces known F<*.js> files with symlinks to F</usr/share/javascript/>
and generates B<${doxygen:Depends}> substitution variable.
=item *
It removes F<*.md5> and F<*.map> files. These are created by doxygen to speed
up incremental runs.
=item *
It generates a B<${doxygen:Built-Using}> substitution variable.
=back
=head1 OPTIONS
=over 4
=item I<directory>
By default, B<dh_doxygen> scans your package looking for directories looking
like they contain doxygen-generated documentation. However, if you explicitly
provide one or more directories, only they will be processed.
=item B<-X>I<item>, B<--exclude=>I<item>
Exclude files that contain I<item> anywhere in their filename from
being symlinked, removed or checked for existence.
=back
=head1 BUGS
Probably.
=cut
use strict;
use warnings;
use File::Find;
use Debian::Debhelper::Dh_Lib;
sub looks_like_doxygen_doc($)
{
my ($path) = @_;
return 0 unless -f "$path/doxygen.css";
return 0 unless -f "$path/doxygen.png";
return 0 unless -f "$path/index.html";
return 1;
}
sub ln_sf($$)
{
my ($orig_target, $orig_source) = my ($target, $source) = @_;
$source =~ s{^debian/[^/]++/+}{} or die;
$target =~ s{^/++}{} or die;
my @source = split(m{/++}, $source);
my @target = split(m{/++}, $target);
@source > 0 and @target > 0 or die;
if ($source[0] eq $target[0])
{
# Make the symlink relative, as per Policy 10.5.
while (@source > 0 and @target > 0 and $source[0] eq $target[0])
{
shift @source;
shift @target;
}
$target = ('../' x $#source) . join('/', @target);
}
else
{
# Keep the symlink absolute, as per Policy 10.5.
$target = $orig_target;
}
doit('ln', '-sf', $target, $orig_source);
}
sub fix_symlinks($)
{
my %deps = ();
my ($path) = @_;
if(-f "$path/jquery.js") {
ln_sf("/usr/share/javascript/jquery/jquery.js", "$path/jquery.js");
$deps{"libjs-jquery"} = 1;
}
return keys %deps;
}
sub drop_cruft($)
{
my ($path) = @_;
my $find_options = "";
if(defined($dh{EXCLUDE_FIND}) && $dh{EXCLUDE_FIND} ne '')
{
$find_options = "! \\( $dh{EXCLUDE_FIND} \\) -a";
}
complex_doit("find $path $find_options -type f -a \\
\\( -name '*.md5' -o -name '*.map' \\) -delete");
}
sub fix_doxygen_doc($$)
{
my ($package, $path) = @_;
return 0 if not looks_like_doxygen_doc($path);
my @deps = fix_symlinks($path);
drop_cruft($path);
map { addsubstvar($package, "doxygen:Depends", $_) } @deps;
my $doxygen_version = `dpkg-query -W -f '\${Version}' doxygen`;
$doxygen_version or die("failed to query version of installed doxygen");
addsubstvar($package, "doxygen:Built-Using", "doxygen (=
$doxygen_version)");
return 1;
}
init();
my @paths = @ARGV;
@paths = (undef) unless @paths;
foreach my $path (@paths)
{
my $done = 0;
foreach my $package (@{$dh{DOPACKAGES}})
{
my $pkgpath = tmpdir($package);
if (defined $path)
{
next if -l $path;
$pkgpath .= "/$path";
$done += fix_doxygen_doc($package, $pkgpath);
}
else
{
$pkgpath .= '/usr/share/doc/';
next unless -d $pkgpath;
find({
wanted => sub {
return unless -d;
return if -l;
return if excludefile($_);
$done += fix_doxygen_doc($package, $_);
},
no_chdir => 1
}, $pkgpath);
}
}
if ($done == 0)
{
my $message = 'Doxygen documentation not found';
$message .= " at $path" if defined $path;
error($message);
}
}
=head1 SEE ALSO
L<debhelper(7)>, L<dh(1)>.
This program is meant to be used together with debhelper.
=head1 AUTHORS
Jakub Wilk <[email protected]>
Helmut Grohne <[email protected]>
=cut
# vim:ts=4 sw=4 et
