Debian Codegraph @

debian/scripts/dh_doxygen

raw
1 #!/usr/bin/perl
2
3 # Copyright © 2011 Jakub Wilk <[email protected]>
4 # Copyright © 2013 Helmut Grohne <[email protected]>
5 #
6 # Redistribution and use in source and binary forms, with or without
7 # modification, are permitted provided that the following conditions are
8 # met:
9 #
10 # * Redistributions of source code must retain the above copyright
11 # notice, this list of conditions and the following disclaimer.
12 #
13 # * Redistributions in binary form must reproduce the above copyright
14 # notice, this list of conditions and the following disclaimer in the
15 # documentation and/or other materials provided with the distribution.
16 #
17 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28
29 =head1 NAME
30
31 dh_doxygen - helps with packaging doxygen-generated documentation
32
33 =head1 SYNOPSIS
34
35 dh_doxygen [S<I<debhelper options>>] [B<-X>I<item>] [I<directory>...]
36
37 =head1 DESCRIPTION
38
39 B<dh_doxygen> is a debhelper program that prepares doxygen-generated
40 documentation for inclusion in a Debian package. More specifically:
41
42 =over 4
43
44 =item *
45
46 It replaces known F<*.js> files with symlinks to F</usr/share/javascript/>
47 and generates B<${doxygen:Depends}> substitution variable.
48
49 =item *
50
51 It removes F<*.md5> and F<*.map> files. These are created by doxygen to speed
52 up incremental runs.
53
54 =item *
55
56 It generates a B<${doxygen:Built-Using}> substitution variable.
57
58 =back
59
60 =head1 OPTIONS
61
62 =over 4
63
64 =item I<directory>
65
66 By default, B<dh_doxygen> scans your package looking for directories looking
67 like they contain doxygen-generated documentation. However, if you explicitly
68 provide one or more directories, only they will be processed.
69
70 =item B<-X>I<item>, B<--exclude=>I<item>
71
72 Exclude files that contain I<item> anywhere in their filename from
73 being symlinked, removed or checked for existence.
74
75 =back
76
77 =head1 BUGS
78
79 Probably.
80
81 =cut
82
83 use strict;
84 use warnings;
85
86 use File::Find;
87 use Debian::Debhelper::Dh_Lib;
88
89 sub looks_like_doxygen_doc($)
90 {
91 my ($path) = @_;
92 return 0 unless -f "$path/doxygen.css";
93 return 0 unless -f "$path/doxygen.png";
94 return 0 unless -f "$path/index.html";
95 return 1;
96 }
97
98 sub ln_sf($$)
99 {
100 my ($orig_target, $orig_source) = my ($target, $source) = @_;
101 $source =~ s{^debian/[^/]++/+}{} or die;
102 $target =~ s{^/++}{} or die;
103 my @source = split(m{/++}, $source);
104 my @target = split(m{/++}, $target);
105 @source > 0 and @target > 0 or die;
106 if ($source[0] eq $target[0])
107 {
108 # Make the symlink relative, as per Policy 10.5.
109 while (@source > 0 and @target > 0 and $source[0] eq $target[0])
110 {
111 shift @source;
112 shift @target;
113 }
114 $target = ('../' x $#source) . join('/', @target);
115 }
116 else
117 {
118 # Keep the symlink absolute, as per Policy 10.5.
119 $target = $orig_target;
120 }
121 doit('ln', '-sf', $target, $orig_source);
122 }
123
124 sub fix_symlinks($)
125 {
126 my %deps = ();
127 my ($path) = @_;
128 if(-f "$path/jquery.js") {
129 ln_sf("/usr/share/javascript/jquery/jquery.js", "$path/jquery.js");
130 $deps{"libjs-jquery"} = 1;
131 }
132 return keys %deps;
133 }
134
135 sub drop_cruft($)
136 {
137 my ($path) = @_;
138 my $find_options = "";
139 if(defined($dh{EXCLUDE_FIND}) && $dh{EXCLUDE_FIND} ne '')
140 {
141 $find_options = "! \\( $dh{EXCLUDE_FIND} \\) -a";
142 }
143 complex_doit("find $path $find_options -type f -a \\
144 \\( -name '*.md5' -o -name '*.map' \\) -delete");
145 }
146
147 sub fix_doxygen_doc($$)
148 {
149 my ($package, $path) = @_;
150 return 0 if not looks_like_doxygen_doc($path);
151 my @deps = fix_symlinks($path);
152 drop_cruft($path);
153 map { addsubstvar($package, "doxygen:Depends", $_) } @deps;
154 my $doxygen_version = `dpkg-query -W -f '\${Source:Version}' doxygen`;
155 $doxygen_version or die("failed to query version of installed doxygen");
156 addsubstvar($package, "doxygen:Built-Using", "doxygen (= $doxygen_version)");
157 return 1;
158 }
159
160 init();
161
162 my @paths = @ARGV;
163 @paths = (undef) unless @paths;
164
165 foreach my $path (@paths)
166 {
167 my $done = 0;
168 foreach my $package (@{$dh{DOPACKAGES}})
169 {
170 my $pkgpath = tmpdir($package);
171 if (defined $path)
172 {
173 next if -l $path;
174 $pkgpath .= "/$path";
175 $done += fix_doxygen_doc($package, $pkgpath);
176 }
177 else
178 {
179 $pkgpath .= '/usr/share/doc/';
180 next unless -d $pkgpath;
181 find({
182 wanted => sub {
183 return unless -d;
184 return if -l;
185 return if excludefile($_);
186 $done += fix_doxygen_doc($package, $_);
187 },
188 no_chdir => 1
189 }, $pkgpath);
190 }
191 }
192 if ($done == 0)
193 {
194 my $message = 'Doxygen documentation not found';
195 $message .= " at $path" if defined $path;
196 error($message);
197 }
198 }
199
200 =head1 SEE ALSO
201
202 L<debhelper(7)>, L<dh(1)>.
203
204 This program is meant to be used together with debhelper.
205
206 =head1 AUTHORS
207
208 Jakub Wilk <[email protected]>
209 Helmut Grohne <[email protected]>
210
211 =cut
212
213 # vim:ts=4 sw=4 et