]> git.donarmstrong.com Git - debhelper.git/blobdiff - debhelper.pod
releasing version 8.9.11
[debhelper.git] / debhelper.pod
index d61cc84da057334d4982c9a40c4cfc5e1f762679..98da7362868ed1d21ce85bc26bd4721203d9f0c3 100644 (file)
@@ -195,6 +195,8 @@ The following command line options are supported by all of the B<dh_auto_>I<*>
 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.
 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<dh(1)>, which then passes them to all the 
+B<dh_auto_>I<*> programs.
 
 =over 4
 
 
 =over 4
 
@@ -250,84 +252,7 @@ is manually specified with the B<--buildsystem> option.
 
 =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<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 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<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
 
 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 @@ B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefil
 
 =item v9
 
 
 =item v9
 
-This compatability level is still open for development; use with caution.
+This compatibility level is still open for development; use with caution.
 
 Changes from v8 are:
 
 
 Changes from v8 are:
 
@@ -545,20 +470,121 @@ Changes from v8 are:
 =item - 
 
 Multiarch support. In particular, B<dh_auto_configure> passes
 =item - 
 
 Multiarch support. In particular, B<dh_auto_configure> passes
-multiarch directories to autoconf in --libdir and --libexecdir,
-while B<dh_makeshlibs> 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<dh_strip> compresses debugging symbol files to reduce the installed
+size of -dbg packages.
 
 =item -
 
 B<dh_auto_configure> does not include the source package name
 in --libexecdir when using autoconf.
 
 
 =item -
 
 B<dh_auto_configure> does not include the source package name
 in --libexecdir when using autoconf.
 
+=item -
+
+B<dh> does not default to enabling --with=python-support
+
+=item -
+
+All of the B<dh_auto_>I<*> debhelper programs and B<dh> set
+environment variables listed by B<dpkg-buildflags>, unless
+they are already set. They support DEB_BUILD_OPTIONS=noopt too.
+
+=item -
+
+B<dh_auto_configure> passes CFLAGS to perl F<Makefile.PL> and
+F<Build.PL>
+
 =back
 
 =back
 
 =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<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,
 =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<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc.
 
 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
 
 Once your package uses debhelper to build, be sure to add
 debhelper to your Build-Depends line in F<debian/control>. You should
@@ -605,13 +625,10 @@ Set to B<1> to enable no-act mode.
 =item B<DH_OPTIONS>
 
 Anything in this variable will be prepended to the command line arguments
 =item B<DH_OPTIONS>
 
 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<DH_OPTIONS> is
-by using "Target-specific Variable Values" in your F<debian/rules> file. See
-the make documentation for details on doing this.
+When using L<dh(1)>, it can be passed options that will be passed on to each
+debhelper command, which is generally better than using DH_OPTIONS.
 
 =item B<DH_ALWAYS_EXCLUDE>
 
 
 =item B<DH_ALWAYS_EXCLUDE>