summaryrefslogtreecommitdiff
path: root/debhelper.pod
diff options
context:
space:
mode:
authorJoey Hess <joey@kitenet.net>2011-07-16 21:08:53 -0400
committerJoey Hess <joey@kitenet.net>2011-07-16 21:08:53 -0400
commit3c64646fe484cc9bbb643feaa3b85eb69985cff7 (patch)
treeef6af2ba58c86fbbc59d85fbc65a1cfa0a4996cf /debhelper.pod
parente728984c5811ae76a76e2ee7444446db94d12d7e (diff)
reorg notes section
Diffstat (limited to 'debhelper.pod')
-rw-r--r--debhelper.pod166
1 files changed, 80 insertions, 86 deletions
diff --git a/debhelper.pod b/debhelper.pod
index 2c7d62d..45d9241 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