5 dh_installdocs - install documentation into package build directories
10 use Debian::Debhelper::Dh_Lib;
14 B<dh_installdocs> [S<I<debhelper options>>] [B<-A>] [B<-X>I<item>] [S<I<file> ...>]
18 B<dh_installdocs> is a debhelper program that is responsible for installing
19 documentation into F<usr/share/doc/package> in package build directories.
25 =item debian/I<package>.docs
27 List documentation files to be installed into I<package>.
29 =item F<debian/copyright>
31 The copyright file is installed into all packages, unless a more
32 specific copyright file is available.
34 =item debian/I<package>.copyright
36 =item debian/I<package>.README.Debian
38 =item debian/I<package>.TODO
40 Each of these files is automatically installed if present for a
43 =item F<debian/README.Debian>
47 These files are installed into the first binary package listed in
50 Note that F<README.debian> files are also installed as F<README.Debian>,
51 and F<TODO> files will be installed as F<TODO.Debian> in non-native packages.
53 =item debian/I<package>.doc-base
55 Installed as doc-base control files. Note that the doc-id will be
56 determined from the B<Document:> entry in the doc-base control file in
59 =item debian/I<package>.doc-base.*
61 If your package needs to register more than one document, you need multiple
62 doc-base files, and can name them like this.
72 Install all files specified by command line parameters in ALL packages
75 =item B<-X>I<item>, B<--exclude=>I<item>
77 Exclude files that contain I<item> anywhere in their filename from
78 being installed. Note that this includes doc-base files.
80 =item B<--link-doc=>I<package>
82 Make the documentation directory of all packages acted on be a symlink to
83 the documentation directory of I<package>. This has no effect when acting on
84 I<package> itself, or if the documentation directory to be created already
85 exists when B<dh_installdocs> is run. To comply with policy, I<package> must
86 be a binary package that comes from the same source package.
88 debhelper will try to avoid installing files into linked documentation
89 directories that would cause conflicts with the linked package. The B<-A>
90 option will have no effect on packages with linked documentation
91 directories, and F<copyright>, F<changelog>, F<README.Debian>, and F<TODO> files will
94 (An older method to accomplish the same thing, which is still supported,
95 is to make the documentation directory of a package be a dangling symlink,
96 before calling B<dh_installdocs>.)
100 Install these files as documentation into the first package acted on. (Or
101 in all packages if B<-A> is specified).
107 This is an example of a F<debian/package.docs> file:
111 debian/notes-for-maintainers.txt
118 Note that B<dh_installdocs> will happily copy entire directory hierarchies if
119 you ask it to (similar to B<cp -a>). If it is asked to install a
120 directory, it will install the complete contents of the directory.
122 Note that this command is not idempotent. L<dh_prep(1)> should be called
123 between invocations of this command. Otherwise, it may cause multiple
124 instances of the same text to be added to maintainer scripts.
129 # Create documentation directories on demand. This allows us to use dangling
130 # symlinks for linked documentation directories unless additional files need
134 return if $docdir_created{$package};
135 my $tmp=tmpdir($package);
138 if ($dh{LINK_DOC} && $dh{LINK_DOC} ne $package) {
139 $target="$tmp/usr/share/doc/$dh{LINK_DOC}";
142 $target="$tmp/usr/share/doc/$package";
145 # If this is a symlink, leave it alone.
146 if (! -d $target && ! -l $target) {
147 doit("install","-g",0,"-o",0,"-d",$target);
149 $docdir_created{$package}=1;
153 "link-doc=s" => \$dh{LINK_DOC},
156 foreach my $package (@{$dh{DOPACKAGES}}) {
157 next if is_udeb($package);
159 my $tmp=tmpdir($package);
160 my $file=pkgfile($package,"docs");
161 my $link_doc=($dh{LINK_DOC} && $dh{LINK_DOC} ne $package);
164 # Make sure that the parent directory exists.
165 if (! -d "$tmp/usr/share/doc" && ! -l "$tmp/usr/share/doc") {
166 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc");
168 # Create symlink to another documentation directory if
170 if (! -d "$tmp/usr/share/doc/$package" &&
171 ! -l "$tmp/usr/share/doc/$package") {
172 doit("ln", "-sf", $dh{LINK_DOC}, "$tmp/usr/share/doc/$package");
173 # Policy says that if you make your documentation
174 # directory a symlink, then you have to depend on
176 addsubstvar($package, "misc:Depends", $dh{LINK_DOC});
180 ensure_docdir($package);
186 @docs=filearray($file, ".");
189 if (($package eq $dh{FIRSTPACKAGE} || ($dh{PARAMS_ALL} && ! $link_doc)) && @ARGV) {
195 if ($dh{EXCLUDE_FIND}) {
196 $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
199 # ignore empty files in subdirs
200 $exclude .= ' -and ! -empty';
202 foreach my $doc (@docs) {
203 next if excludefile($doc);
204 next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files
205 ensure_docdir($package);
206 if (-d $doc && length $exclude) {
207 my $basename = basename($doc);
208 my $dir = ($basename eq '.') ? $doc : "$doc/..";
211 complex_doit("cd '$dir' && find '$basename' \\( -type f -or -type l \\)$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
214 doit("cp", "-a", $doc, "$tmp/usr/share/doc/$package");
217 doit("chown","-R","0:0","$tmp/usr/share/doc");
218 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
219 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
222 # .Debian is correct, according to policy, but I'm easy.
223 my $readme_debian=pkgfile($package,'README.Debian');
224 if (! $readme_debian) {
225 $readme_debian=pkgfile($package,'README.debian');
227 if (! $link_doc && $readme_debian && ! excludefile($readme_debian)) {
228 ensure_docdir($package);
229 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
230 "$tmp/usr/share/doc/$package/README.Debian");
233 my $todo=pkgfile($package,'TODO');
234 if (! $link_doc && $todo && ! excludefile($todo)) {
235 ensure_docdir($package);
236 if (isnative($package)) {
237 doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
238 "$tmp/usr/share/doc/$package/TODO");
241 doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
242 "$tmp/usr/share/doc/$package/TODO.Debian");
246 # If the "directory" is a dangling symlink, then don't install
247 # the copyright file. This is useful for multibinary packages
248 # that share a doc directory.
249 if (! $link_doc && (! -l "$tmp/usr/share/doc/$package" || -d "$tmp/usr/share/doc/$package")) {
250 # Support debian/package.copyright, but if not present, fall
251 # back on debian/copyright for all packages, not just the
252 # main binary package.
253 my $copyright=pkgfile($package,'copyright');
254 if (! $copyright && -e "debian/copyright") {
255 $copyright="debian/copyright";
257 if ($copyright && ! excludefile($copyright)) {
258 ensure_docdir($package);
259 doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
260 "$tmp/usr/share/doc/$package/copyright");
264 # Handle doc-base files. There are two filename formats, the usual
265 # plus an extended format (debian/package.*).
268 opendir(DEB,"debian/") || error("can't read debian directory: $!");
269 # If this is the main package, we need to handle unprefixed filenames.
270 # For all packages, we must support both the usual filename format plus
271 # that format with a period an something appended.
272 my $regexp="\Q$package\E\.";
273 if ($package eq $dh{MAINPACKAGE}) {
274 $regexp="(|$regexp)";
276 foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
277 # .EX are example files, generated by eg, dh-make
278 next if $fn=~/\.EX$/;
279 next if excludefile($fn);
280 # Parse the file to get the doc id.
281 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
284 if (/^Document\s*:\s*(.*)/) {
289 if (! exists $doc_ids{$fn}) {
290 warning("Could not parse $fn for doc-base Document id; skipping");
297 if (! -d "$tmp/usr/share/doc-base/") {
298 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
301 foreach my $fn (keys %doc_ids) {
302 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
303 "$tmp/usr/share/doc-base/$doc_ids{$fn}");
311 This program is a part of debhelper.
315 Joey Hess <joeyh@debian.org>