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 dh_installdocs is a debhelper program that is responsible for installing
19 documentation into usr/share/doc/package in package build directories.
21 dh_installdocs automatically installs debian/copyright if it exists. If
22 dh_installdocs is acting on multiple packages, debian/copyright files will be
23 installed into all packages. However, if you need to have separate copyright
24 files for different binary packages, you can use files named
25 debian/package.copyright.
27 Any filenames specified as parameters will be installed into the first
28 package dh_installdocs is told to act on. By default, this is the first
29 binary package in debian/control, but if you use B<-p>, B<-i>, or B<-a> flags, it
30 will be the first package specified by those flags.
32 Also, debian/README.Debian (or debian/README.debian) and debian/TODO, if
33 they exist, will be installed into the first binary package listed in
34 debian/control, if dh_installdocs is acting on that package. Note that
35 debian/TODO will be installed named TODO.Debian, if the package is not a
36 debian native package. Also note that README.debian is installed as
37 README.Debian, for consistency. Note that debian/package.README.Debian and
38 debian/package.TODO can be used to specify files for subpackages.
40 Files named debian/package.docs can list other files to be installed.
42 Files named debian/package.doc-base, will be installed as doc-base control
43 files. Note that the doc-id will be determined from the "Document:" entry
44 in the doc-base control file in question.
46 If your package needs to register more than one document, you need multiple
47 files. To accomplish this, you can use files named debian/package.doc-base.*
55 Install all files specified by command line parameters in ALL packages
58 =item B<-Xitem>, B<--exclude=item>
60 Exclude files that contain "item" anywhere in their filename from
61 being installed. Note that this includes doc-base files.
65 Install these files as documentation into the first package acted on. (Or
66 in all packages if B<-A> is specified).
72 This is an example of a debian/package.docs file:
76 debian/notes-for-maintainers.txt
83 Note that dh_installdocs will happily copy entire directory hierarchies if
84 you ask it to (similar to cp -a). If it is asked to install a
85 directory, it will install the complete contents of the directory.
87 Note that this command is not idempotent. L<dh_prep(1)> should be called
88 between invocations of this command. Otherwise, it may cause multiple
89 instances of the same text to be added to maintainer scripts.
95 foreach my $package (@{$dh{DOPACKAGES}}) {
96 next if is_udeb($package);
98 my $tmp=tmpdir($package);
99 my $file=pkgfile($package,"docs");
101 # If this is a symlink, leave it alone.
102 if ( ! -d "$tmp/usr/share/doc/$package" &&
103 ! -l "$tmp/usr/share/doc/$package") {
104 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc/$package");
110 @docs=filearray($file, ".");
113 if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
119 if ($dh{EXCLUDE_FIND}) {
120 $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)';
123 # ignore empty files in subdirs
124 $exclude .= ' -and ! -empty';
126 foreach my $doc (@docs) {
127 next if excludefile($doc);
128 next if -e $doc && ! -s $doc && ! compat(4); # ignore empty files
129 if (-d $doc && length $exclude) {
130 my $basename = basename($doc);
131 my $dir = ($basename eq '.') ? $doc : "$doc/..";
134 complex_doit("cd '$dir' && find '$basename' \\( -type f -or -type l \\)$exclude -exec cp --parents -dp {} $pwd/$tmp/usr/share/doc/$package \\;");
137 doit("cp", "-a", $doc, "$tmp/usr/share/doc/$package");
140 doit("chown","-R","0:0","$tmp/usr/share/doc");
141 doit("chmod","-R","go=rX","$tmp/usr/share/doc");
142 doit("chmod","-R","u+rw","$tmp/usr/share/doc");
145 # .Debian is correct, according to policy, but I'm easy.
146 my $readme_debian=pkgfile($package,'README.Debian');
147 if (! $readme_debian) {
148 $readme_debian=pkgfile($package,'README.debian');
150 if ($readme_debian && ! excludefile($readme_debian)) {
151 doit("install","-g",0,"-o",0,"-m","644","-p","$readme_debian",
152 "$tmp/usr/share/doc/$package/README.Debian");
155 my $todo=pkgfile($package,'TODO');
156 if ($todo && ! excludefile($todo)) {
157 if (isnative($package)) {
158 doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
159 "$tmp/usr/share/doc/$package/TODO");
162 doit("install","-g",0,"-o",0,"-m","644","-p",$todo,
163 "$tmp/usr/share/doc/$package/TODO.Debian");
167 # If the "directory" is a dangling symlink, then don't install
168 # the copyright file. This is useful for multibinary packages
169 # that share a doc directory.
170 if (-d "$tmp/usr/share/doc/$package") {
171 # Support debian/package.copyright, but if not present, fall
172 # back on debian/copyright for all packages, not just the
173 # main binary package.
174 my $copyright=pkgfile($package,'copyright');
175 if (! $copyright && -e "debian/copyright") {
176 $copyright="debian/copyright";
178 if ($copyright && ! excludefile($copyright)) {
179 doit("install","-g",0,"-o",0,"-m","644","-p",$copyright,
180 "$tmp/usr/share/doc/$package/copyright");
184 # Handle doc-base files. There are two filename formats, the usual
185 # plus an extended format (debian/package.*).
188 opendir(DEB,"debian/") || error("can't read debian directory: $!");
189 # If this is the main package, we need to handle unprefixed filenames.
190 # For all packages, we must support both the usual filename format plus
191 # that format with a period an something appended.
192 my $regexp="\Q$package\E\.";
193 if ($package eq $dh{MAINPACKAGE}) {
194 $regexp="(|$regexp)";
196 foreach my $fn (grep {/^${regexp}doc-base(\..*)?$/} readdir(DEB)) {
197 # .EX are example files, generated by eg, dh-make
198 next if $fn=~/\.EX$/;
199 next if excludefile($fn);
200 # Parse the file to get the doc id.
201 open (IN, "debian/$fn") || die "Cannot read debian/$fn.";
204 if (/^Document\s*:\s*(.*)/) {
214 if (! -d "$tmp/usr/share/doc-base/") {
215 doit("install","-g",0,"-o",0,"-d","$tmp/usr/share/doc-base/");
218 foreach my $fn (keys %doc_ids) {
219 doit("install","-g",0,"-o",0,"-m644","-p","debian/$fn",
220 "$tmp/usr/share/doc-base/$doc_ids{$fn}");
228 This program is a part of debhelper.
232 Joey Hess <joeyh@debian.org>