diff options
Diffstat (limited to 'debhelper.pod')
| -rw-r--r-- | debhelper.pod | 166 |
1 files changed, 80 insertions, 86 deletions
diff --git a/debhelper.pod b/debhelper.pod index 2c7d62d7..45d9241f 100644 --- a/debhelper.pod +++ b/debhelper.pod @@ -191,7 +191,7 @@ in ALL packages acted on, not just the first. =head1 BUILD SYSTEM OPTIONS -All of the B<dh_auto_>I<*> debhelper programs sets environment variables +All of the B<dh_auto_>I<*> debhelper programs set environment variables listed by B<dpkg-buildflags>, unless they are already set. They support DEB_BUILD_OPTIONS=noopt too. @@ -254,84 +254,7 @@ is manually specified with the B<--buildsystem> option. =back -=head1 NOTES - -=head2 Multiple binary package support - -If your source package generates more than one binary package, debhelper -programs will default to acting on all binary packages when run. If your -source package happens to generate one architecture dependent package, and -another architecture independent package, this is not the correct behavior, -because you need to generate the architecture dependent packages in the -binary-arch F<debian/rules> target, and the architecture independent packages -in the binary-indep F<debian/rules> target. - -To facilitate this, as well as give you more control over which packages -are acted on by debhelper programs, all debhelper programs accept the -B<-a>, B<-i>, B<-p>, and B<-s> parameters. These parameters are cumulative. -If none are given, debhelper programs default to acting on all packages listed -in the control file. - -=head2 Automatic generation of Debian install scripts - -Some debhelper commands will automatically generate parts of Debian -maintainer scripts. If you want these automatically generated things -included in your existing Debian maintainer scripts, then you need to add -B<#DEBHELPER#> to your scripts, in the place the code should be added. -B<#DEBHELPER#> will be replaced by any auto-generated code when you run -B<dh_installdeb>. - -If a script does not exist at all and debhelper needs to add something to -it, then debhelper will create the complete script. - -All debhelper commands that automatically generate code in this way let it -be disabled by the -n parameter (see above). - -Note that the inserted code will be shell code, so you cannot directly use -it in a Perl script. If you would like to embed it into a Perl script, here -is one way to do that (note that I made sure that $1, $2, etc are set with -the set command): - - my $temp="set -e\nset -- @ARGV\n" . << 'EOF'; - #DEBHELPER# - EOF - system ($temp) / 256 == 0 - or die "Problem with debhelper scripts: $!"; - -=head2 Automatic generation of miscellaneous dependencies. - -Some debhelper commands may make the generated package need to depend on -some other packages. For example, if you use L<dh_installdebconf(1)>, your -package will generally need to depend on debconf. Or if you use -L<dh_installxfonts(1)>, your package will generally need to depend on a -particular version of xutils. Keeping track of these miscellaneous -dependencies can be annoying since they are dependent on how debhelper does -things, so debhelper offers a way to automate it. - -All commands of this type, besides documenting what dependencies may be -needed on their man pages, will automatically generate a substvar called -B<${misc:Depends}>. If you put that token into your F<debian/control> file, it -will be expanded to the dependencies debhelper figures you need. - -This is entirely independent of the standard B<${shlibs:Depends}> generated by -L<dh_makeshlibs(1)>, and the B<${perl:Depends}> generated by L<dh_perl(1)>. -You can choose not to use any of these, if debhelper's guesses don't match -reality. - -=head2 Package build directories - -By default, all debhelper programs assume that the temporary directory used -for assembling the tree of files in a package is debian/I<package>. - -Sometimes, you might want to use some other temporary directory. This is -supported by the B<-P> flag. For example, "B<dh_installdocs -Pdebian/tmp>", will -use B<debian/tmp> as the temporary directory. Note that if you use B<-P>, the -debhelper programs can only be acting on a single package at a time. So if -you have a package that builds many binary packages, you will need to also -use the B<-p> flag to specify which binary package the debhelper program will -act on. - -=head2 Debhelper compatibility levels +=head1 COMPATABILITY LEVELS From time to time, major non-backwards-compatible changes need to be made to debhelper, to keep it clean and well-designed as needs change and its @@ -569,6 +492,83 @@ B<dh> does not default to enabling --with=python-support =back +=head1 NOTES + +=head2 Multiple binary package support + +If your source package generates more than one binary package, debhelper +programs will default to acting on all binary packages when run. If your +source package happens to generate one architecture dependent package, and +another architecture independent package, this is not the correct behavior, +because you need to generate the architecture dependent packages in the +binary-arch F<debian/rules> target, and the architecture independent packages +in the binary-indep F<debian/rules> target. + +To facilitate this, as well as give you more control over which packages +are acted on by debhelper programs, all debhelper programs accept the +B<-a>, B<-i>, B<-p>, and B<-s> parameters. These parameters are cumulative. +If none are given, debhelper programs default to acting on all packages listed +in the control file. + +=head2 Automatic generation of Debian install scripts + +Some debhelper commands will automatically generate parts of Debian +maintainer scripts. If you want these automatically generated things +included in your existing Debian maintainer scripts, then you need to add +B<#DEBHELPER#> to your scripts, in the place the code should be added. +B<#DEBHELPER#> will be replaced by any auto-generated code when you run +B<dh_installdeb>. + +If a script does not exist at all and debhelper needs to add something to +it, then debhelper will create the complete script. + +All debhelper commands that automatically generate code in this way let it +be disabled by the -n parameter (see above). + +Note that the inserted code will be shell code, so you cannot directly use +it in a Perl script. If you would like to embed it into a Perl script, here +is one way to do that (note that I made sure that $1, $2, etc are set with +the set command): + + my $temp="set -e\nset -- @ARGV\n" . << 'EOF'; + #DEBHELPER# + EOF + system ($temp) / 256 == 0 + or die "Problem with debhelper scripts: $!"; + +=head2 Automatic generation of miscellaneous dependencies. + +Some debhelper commands may make the generated package need to depend on +some other packages. For example, if you use L<dh_installdebconf(1)>, your +package will generally need to depend on debconf. Or if you use +L<dh_installxfonts(1)>, your package will generally need to depend on a +particular version of xutils. Keeping track of these miscellaneous +dependencies can be annoying since they are dependent on how debhelper does +things, so debhelper offers a way to automate it. + +All commands of this type, besides documenting what dependencies may be +needed on their man pages, will automatically generate a substvar called +B<${misc:Depends}>. If you put that token into your F<debian/control> file, it +will be expanded to the dependencies debhelper figures you need. + +This is entirely independent of the standard B<${shlibs:Depends}> generated by +L<dh_makeshlibs(1)>, and the B<${perl:Depends}> generated by L<dh_perl(1)>. +You can choose not to use any of these, if debhelper's guesses don't match +reality. + +=head2 Package build directories + +By default, all debhelper programs assume that the temporary directory used +for assembling the tree of files in a package is debian/I<package>. + +Sometimes, you might want to use some other temporary directory. This is +supported by the B<-P> flag. For example, "B<dh_installdocs -Pdebian/tmp>", will +use B<debian/tmp> as the temporary directory. Note that if you use B<-P>, the +debhelper programs can only be acting on a single package at a time. So if +you have a package that builds many binary packages, you will need to also +use the B<-p> flag to specify which binary package the debhelper program will +act on. + =head2 udebs Debhelper includes support for udebs. To create a udeb with debhelper, @@ -578,13 +578,7 @@ comply with debian-installer policy, by making the generated package files end in F<.udeb>, not installing any documentation into a udeb, skipping over F<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc. -=head2 Other notes - -In general, if any debhelper program needs a directory to exist under -B<debian/>, it will create it. I haven't bothered to document this in all the -man pages, but for example, B<dh_installdeb> knows to make debian/I<package>/DEBIAN/ -before trying to put files there, B<dh_installmenu> knows you need a -debian/I<package>/usr/share/menu/ before installing the menu files, etc. +=head2 Build depends Once your package uses debhelper to build, be sure to add debhelper to your Build-Depends line in F<debian/control>. You should |