Debian Codegraph @

debian/dh-doxygen/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 removes F<*.md5> and F<*.map> files. These are created by doxygen to speed
47 up incremental runs.
48
49 =back
50
51 =head1 OPTIONS
52
53 =over 4
54
55 =item I<directory>
56
57 By default, B<dh_doxygen> scans your package looking for directories looking
58 like they contain doxygen-generated documentation. However, if you explicitly
59 provide one or more directories, only they will be processed.
60
61 =item B<-X>I<item>, B<--exclude=>I<item>
62
63 Exclude files that contain I<item> anywhere in their filename from
64 being symlinked, removed or checked for existence.
65
66 =back
67
68 =head1 BUGS
69
70 Probably.
71
72 =cut
73
74 use strict;
75 use warnings;
76
77 use File::Find;
78 use Debian::Debhelper::Dh_Lib;
79
80 sub looks_like_doxygen_doc($)
81 {
82 my ($path) = @_;
83 return 0 unless -f "$path/doxygen.css";
84 return 0 unless -f "$path/doxygen.svg";
85 return 0 unless -f "$path/index.html";
86 return 1;
87 }
88
89 sub drop_cruft($)
90 {
91 my ($path) = @_;
92 my $find_options = "";
93 if(defined($dh{EXCLUDE_FIND}) && $dh{EXCLUDE_FIND} ne '')
94 {
95 $find_options = "! \\( $dh{EXCLUDE_FIND} \\) -a";
96 }
97 complex_doit("find $path $find_options -type f -a \\
98 \\( -name '*.md5' -o -name '*.map' \\) -delete");
99 }
100
101 sub fix_doxygen_doc($$)
102 {
103 my ($package, $path) = @_;
104 return 0 if not looks_like_doxygen_doc($path);
105 drop_cruft($path);
106 return 1;
107 }
108
109 init();
110
111 my @paths = @ARGV;
112 @paths = (undef) unless @paths;
113
114 foreach my $path (@paths)
115 {
116 my $done = 0;
117 foreach my $package (@{$dh{DOPACKAGES}})
118 {
119 my $pkgpath = tmpdir($package);
120 if (defined $path)
121 {
122 next if -l $path;
123 $pkgpath .= "/$path";
124 $done += fix_doxygen_doc($package, $pkgpath);
125 }
126 else
127 {
128 $pkgpath .= '/usr/share/doc/';
129 next unless -d $pkgpath;
130 find({
131 wanted => sub {
132 return unless -d;
133 return if -l;
134 return if excludefile($_);
135 $done += fix_doxygen_doc($package, $_);
136 },
137 no_chdir => 1
138 }, $pkgpath);
139 }
140 }
141 if ($done == 0)
142 {
143 my $message = 'Doxygen documentation not found';
144 $message .= " at $path" if defined $path;
145 error($message);
146 }
147 }
148
149 =head1 SEE ALSO
150
151 L<debhelper(7)>, L<dh(1)>.
152
153 This program is meant to be used together with debhelper.
154
155 =head1 AUTHORS
156
157 Jakub Wilk <[email protected]>
158 Helmut Grohne <[email protected]>
159
160 =cut
161
162 # vim:ts=4 sw=4 et