X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=debhelper.pod;h=98da7362868ed1d21ce85bc26bd4721203d9f0c3;hb=a4cf3e83f425663c6c190791fe3ea92b7143191a;hp=d61cc84da057334d4982c9a40c4cfc5e1f762679;hpb=cbe68c8579e8abc03aeff939306b2d34cb1fe8ac;p=debhelper.git diff --git a/debhelper.pod b/debhelper.pod index d61cc84..98da736 100644 --- a/debhelper.pod +++ b/debhelper.pod @@ -195,6 +195,8 @@ The following command line options are supported by all of the BI<*> debhelper programs. These programs support a variety of build systems, and normally heuristically determine which to use, and how to use them. You can use these command line options to override the default behavior. +Typically these are passed to L, which then passes them to all the +BI<*> programs. =over 4 @@ -250,84 +252,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 target, and the architecture independent packages -in the binary-indep F 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. - -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, your -package will generally need to depend on debconf. Or if you use -L, 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 dependant 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 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, and the B<${perl:Depends}> generated by L. -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. - -Sometimes, you might want to use some other temporary directory. This is -supported by the B<-P> flag. For example, "B", will -use B 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 @@ -536,7 +461,7 @@ BI<*> prefer to use Perl's B in preference to F passes -multiarch directories to autoconf in --libdir and --libexecdir, -while B detects packages containing multiarch -directories and sets a Pre-Dependency on multiarch-support in -${misc:Pre-Depends} +multiarch directories to autoconf in --libdir and --libexecdir. + +=item - + +dh is aware of the usual dependencies between targets in debian/rules. +So, "dh binary" will run any build, build-arch, build-indep, install, +etc targets that exist in the rules file. There's no need to define an +explicit binary target with explicit dependencies on the other targets. + +=item - + +B compresses debugging symbol files to reduce the installed +size of -dbg packages. =item - B does not include the source package name in --libexecdir when using autoconf. +=item - + +B does not default to enabling --with=python-support + +=item - + +All of the BI<*> debhelper programs and B set +environment variables listed by B, unless +they are already set. They support DEB_BUILD_OPTIONS=noopt too. + +=item - + +B passes CFLAGS to perl F and +F + =back =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 target, and the architecture independent packages +in the binary-indep F 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. + +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, your +package will generally need to depend on debconf. Or if you use +L, 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 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, and the B<${perl:Depends}> generated by L. +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. + +Sometimes, you might want to use some other temporary directory. This is +supported by the B<-P> flag. For example, "B", will +use B 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, @@ -568,13 +594,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, F, F, and F scripts, etc. -=head2 Other notes - -In general, if any debhelper program needs a directory to exist under -B, it will create it. I haven't bothered to document this in all the -man pages, but for example, B knows to make debian/I/DEBIAN/ -before trying to put files there, B knows you need a -debian/I/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. You should @@ -605,13 +625,10 @@ Set to B<1> to enable no-act mode. =item B Anything in this variable will be prepended to the command line arguments -of all debhelper commands. Command-specific options will be ignored by -commands that do not support them. +of all debhelper commands. -This is useful in some situations, for example, if you need to pass B<-p> to -all debhelper commands that will be run. One good way to set B is -by using "Target-specific Variable Values" in your F file. See -the make documentation for details on doing this. +When using L, it can be passed options that will be passed on to each +debhelper command, which is generally better than using DH_OPTIONS. =item B