debhelper.1

   1 .TH DEBHELPER 1 "" "Debhelper Commands" "Debhelper Commands"
   2 .SH NAME
   3 debhelper \- overview of the debhelper commands
   4 .SH SYNOPSIS
   5 .B dh_*
   6 .I "[-v] [-a] [-i] [-s] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]"
   7 .SH "DESCRIPTION"
   8 Debhelper is used to help you build a debian package. The philospohy behind
   9 debhelper is to provide a collection of small, simple, and easily
  10 understood tools that are used in debian/rules to automate various common
  11 aspects of building a package. This means less work for you, the packager.
  12 It also, to some degree means that these tools can be changed if debian
  13 policy changes, and packages that use them will require only a rebuild to
  14 comply with the new policy.
  15 .P
  16 A typical debian/rules file that uses debhelper will call several debhelper
  17 commands in sequence. Debhelper commands are all named with a "dh_" prefix.
  18 Examples of rules files that use debhelper are in
  19 /usr/share/doc/debhelper/examples/ .
  20 .P
  21 To create a new debian package using debhelper, you can just copy one of
  22 the sample rules files and edit it by hand. Or you can try the dh-make
  23 package, which contains a
  24 .BR dh_make (1)
  25 command that partially automates the process. For a more gentle
  26 introduction, the maint-guide debian package contains a
  27 tutorial about making your first package using debhelper.
  28 .SH "DEBHELPER COMMANDS"
  29 Here is the complete list of available debhelper commands. See their man
  30 pages for additional documentation.
  31 #LIST#
  32 .SH "SHARED DEBHLPER OPTIONS"
  33 The following command line options are supported by all debhelper programs.
  34 .TP
  35 .B \-v, \--verbose
  36 Verbose mode: show all commands that modify the package build directory.
  37 .TP
  38 .B \--no-act
  39 Do not really do anything. If used with -v, the result is that the command
  40 will output a list of what it would have done.
  41 .TP
  42 .B \-a, \--arch
  43 Act on all architecture dependent packages.
  44 .TP
  45 .B \-i, \--indep
  46 Act on all architecture independent packages.
  47 .TP
  48 .B \-ppackage, \--package=package
  49 Act on the package named "package".
  50 .TP
  51 .B \-s, \--same-arch
  52 This is a smarter version of the -a flag, that is used in some rare
  53 circumstances. It understands that if the control file lists "Architecture: i386"
  54 for the package, the package should not be acted on on other architectures. So
  55 this flag makes the command act on all "Architecture: any" packages, as well
  56 as on any packages that have the current architecture explicitly specified.
  57 Contrast to the -a flag, which makes the command work on all packages that
  58 are not architecture independant.
  59 .TP
  60 .B \-Npackage, \--no-package=package
  61 Do not act on the specified package even if an -a, -i, or -p option lists
  62 the package as one that should be acted on.
  63 .TP
  64 .B \-Ptmpdir, \--tmpdir=tmpdir
  65 Use "tmpdir" for package build directory. The default is debian/<package>
  66 .SH "COMMON DEBHELPER OPTIONS"
  67 The following command line options are supported by some debhelper programs.
  68 See the man page of each program for a complete explanation of what the
  69 option does.
  70 .TP
  71 .B \-n
  72 Do not modify postinst/postrm/etc scripts.
  73 .TP
  74 .B \-Xitem, \--exclude=item
  75 Exclude an item from processing.
  76 .TP
  77 .B \-A, \-all
  78 Makes files or other items that are specified on the command line take effect
  79 in ALL packages acted on, not just the first.
  80 .SH NOTES
  81 .TP
  82 .B Multiple binary package support
  83 .RS
  84 If your source package generates more than one binary package, debhelper
  85 programs will default to acting on all binary packages when run. If your
  86 source package happens to generate one architecture dependent package, and
  87 another architecture independent package, this is not the correct behavior,
  88 because you need to generate the architecture dependent packages in the
  89 binary-arch debian/rules target, and the architecture independent packages
  90 in the binary-indep debian/rules target.
  91
  92 To facilitate this, as well as give you more control over which packages
  93 are acted on by debhelper programs, all debhelper programs accept the
  94 .B -a
  95 ,
  96 .B -i
  97 ,
  98 .B -p
  99 , and
 100 .B -s
 101 parameters. These parameters are cumulative. If none are given,
 102 debhelper programs default to acting on all packages listed in the control
 103 file.
 104 .P
 105 See
 106 .BR /usr/share/doc/debhelper/examples/rules.multi
 107 for an example of how to use this.
 108 .RE
 109 .TP
 110 .B Automatic generation of debian install scripts
 111 .RS
 112 Some debhelper commands will automatically generate parts of debian install
 113 scripts. If you want these automatically generated things included in your
 114 debian install scripts, then you need to add "#DEBHELPER#" to your scripts,
 115 in the place the code should be added. "#DEBHELPER#" will be replaced by
 116 any auto-generated code when you run dh_installdeb.
 117 .P
 118 All scripts that automatically generate code in this way let it be disabled
 119 by the -n parameter (see above).
 120 .P
 121 Note that the inserted code will be shell code, so you cannot directly use
 122 it in a perl script. If you would like to embed it into a perl script, here
 123 is one way to do that (note that I made sure that $1, $2, etc are set with
 124 the set command):
 125   my $temp="set -e\\nset -- @ARGV\\n" . << 'EOF';
 126   #DEBHELPER#
 127   EOF
 128   system ($temp) / 256 == 0
 129         or die "Problem with debhelper scripts: $!";
 130 .RE
 131 .TP
 132 .B Package build directories
 133 .RS
 134 By default, all debhelper programs assume that the temporary directory used
 135 for assembling the tree of files in a package is debian/<packagename>.
 136 .P
 137 Sometimes, you might want to use some other temporary directory. This is
 138 supported by the
 139 .B -P
 140 flag. For example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the
 141 temporary directory. Note that if you use -P, the debhelper programs can only
 142 be acting on a single package at a time. So if you have a package that builds
 143 many binary packages, you will need to use the -p flag to specify which
 144 binary package the debhelper program will act on.
 145 .RE
 146 .TP
 147 .B Debhelper compatability levels
 148 .RS
 149 From time to time, major non-backwards-compatabile changes need to be made
 150 to debhelper, to keep it clean and well-designed as needs change and its
 151 author gains more experience. To prevent such major changes from breaking
 152 existing packages, the DH_COMPAT environment variable was introduced.
 153 DH_COMPAT may be set to a number, to determine which major revision of
 154 debhelper should be used. There are currently 3:
 155 .TP
 156 .B V1
 157 Setting DH_COMPAT=1 (or leaving it unset) causes debhelper to act in
 158 compatability mode. It will use debian/tmp as the package tree
 159 directory for the first binary package listed in the control file, while using
 160 debian/<package> for all other packages listed in the control file.
 161 This mode is deprecated.
 162 .TP
 163 .B V2
 164 Setting DH_COMPAT=2 causes debhelper to consitently use debian/<package>
 165 as the package tree directory for every package that is built. This
 166 mode is currently set by default in all the example rules files, and you
 167 are encouraged to use it.
 168 .TP
 169 .B V3
 170 Setting DH_COMPAT=3 will make debhelper start using new v3 features as
 171 they are implemented. This will cause its behavior to change without
 172 notice, and so may break packages that use it. See the file
 173 "/usr/share/doc/debhelper/v3" for more information about planned
 174 changes.
 175 .RE
 176 .TP
 177 .B Other notes
 178 .RS
 179 In general, if any debhelper program needs a directory to exist under
 180 debian/, it will create it. I haven't bothered to document this in all the
 181 man pages, but for example, dh_installdeb knows to make debian/<foo>/DEBIAN/
 182 before trying to put files there, dh_installmenu knows you need a
 183 debian/<foo>/usr/lib/menu/ before installing the menu files, etc.
 184 .P
 185 Note that if you are generating a debian package that has arch-indep and
 186 arch-dependent portions, and you are using dh_movefiles to move the
 187 arch-indep files out of debian/tmp, you need to make sure that dh_movefiles
 188 does this even if only the arch-dependent package is being built (for
 189 ports to other architectures). I handle this in the example rules file
 190 "rules.multi" by calling dh_movefiles in the install target.
 191 .P
 192 Once your package uses debhelper to build, be sure to add
 193 debhelper to your Build-Depends line in debian/control.
 194 .RE
 195 .SH ENVIRONMENT
 196 .TP
 197 .I DH_VERBOSE
 198 Enables verbose mode.
 199 .TP
 200 .I DH_COMPAT
 201 Specifies what compatability level debhelper should run at. See above.
 202 .TP
 203 .I DH_NO_ACT
 204 Enables no-act mode.
 205 .TP
 206 .I DH_OPTIONS
 207 Anything in this variable will be prepended to the command line
 208 arguments of all debhelper commands. This in useful in some situations,
 209 for example, if you need to pass -p to all debhelper commands that will be
 210 run. If you use DH_OPTIONS, be sure to use "dh_testversion 1.1.17" - older
 211 debhelpers will ignore it and do things you don't want them to. One very
 212 good way to set DH_OPTIONS is by using "Target-specific Variable Values" in
 213 your debian/rules file. See the make documentation for details on doing this.
 214 .SH "SEE ALSO"
 215 .TP
 216 .BR /usr/share/doc/debhelper/examples/
 217 A set of example debian/rules files that use debhelper.
 218 .TP
 219 .BR http://kitenet.net/programs/debhelper/
 220 Debhelper web site.
 221 .SH AUTHOR
 222 Joey Hess <joeyh@debian.org>