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 "DEBHELPER CONFIG FILES"
  33 Many debhelper commands make use of files in debian/ to control what they
  34 do. Besides the common debian/changelog and debian/control, which are
  35 in all packages, not just those using debhelper, some additional files can
  36 be used to configure the behavior of specific debhelper commands. These
  37 files are typically named debian/<package>.foo (where <package> of course,
  38 is replaced with the package that is being acted on).
  39 .P
  40 For example,
  41 dh_installdocs uses files named debian/<package>.docs to list the documentation
  42 files it will install. See the man pages of individual commands for details
  43 about the names and formats of the files they use.
  44 .P
  45 Note that if a package is the first (or only) binary package listed in
  46 debian/control, debhelper will use debian/foo if no debian/<package>.foo
  47 file can be found.
  48 .P
  49 In some rare cases, you may want to have different versions of these files
  50 for different architectures. If files named debian/<package>.foo.<arch>
  51 exist, where <arch> is the same as the output of "dpkg --print-architecture",
  52 then they will be used in preference to other, more general files.
  53 .P
  54 In many cases, these config files are used to specify various types of
  55 files. Documentation or example files to install, files to move, and so on.
  56 When appropriate, in cases like these, you can use standard shell wildcard
  57 characters ("?" and "*") in the files.
  58 .SH "SHARED DEBHELPER OPTIONS"
  59 The following command line options are supported by all debhelper programs.
  60 .TP
  61 .B \-v, \--verbose
  62 Verbose mode: show all commands that modify the package build directory.
  63 .TP
  64 .B \--no-act
  65 Do not really do anything. If used with -v, the result is that the command
  66 will output a list of what it would have done.
  67 .TP
  68 .B \-a, \--arch
  69 Act on all architecture dependent packages.
  70 .TP
  71 .B \-i, \--indep
  72 Act on all architecture independent packages.
  73 .TP
  74 .B \-ppackage, \--package=package
  75 Act on the package named "package".
  76 .TP
  77 .B \-s, \--same-arch
  78 This is a smarter version of the -a flag, that is used in some rare
  79 circumstances. It understands that if the control file lists "Architecture: i386"
  80 for the package, the package should not be acted on on other architectures. So
  81 this flag makes the command act on all "Architecture: any" packages, as well
  82 as on any packages that have the current architecture explicitly specified.
  83 Contrast to the -a flag, which makes the command work on all packages that
  84 are not architecture independant.
  85 .TP
  86 .B \-Npackage, \--no-package=package
  87 Do not act on the specified package even if an -a, -i, or -p option lists
  88 the package as one that should be acted on.
  89 .TP
  90 .B \-Ptmpdir, \--tmpdir=tmpdir
  91 Use "tmpdir" for package build directory. The default is debian/<package>
  92 .SH "COMMON DEBHELPER OPTIONS"
  93 The following command line options are supported by some debhelper programs.
  94 See the man page of each program for a complete explanation of what the
  95 option does.
  96 .TP
  97 .B \-n
  98 Do not modify postinst/postrm/etc scripts.
  99 .TP
 100 .B \-Xitem, \--exclude=item
 101 Exclude an item from processing. This option may be used multiple times,
 102 to exclude more than one thing.
 103 .TP
 104 .B \-A, \-all
 105 Makes files or other items that are specified on the command line take effect
 106 in ALL packages acted on, not just the first.
 107 .SH NOTES
 108 .TP
 109 .B Multiple binary package support
 110 .RS
 111 If your source package generates more than one binary package, debhelper
 112 programs will default to acting on all binary packages when run. If your
 113 source package happens to generate one architecture dependent package, and
 114 another architecture independent package, this is not the correct behavior,
 115 because you need to generate the architecture dependent packages in the
 116 binary-arch debian/rules target, and the architecture independent packages
 117 in the binary-indep debian/rules target.
 118
 119 To facilitate this, as well as give you more control over which packages
 120 are acted on by debhelper programs, all debhelper programs accept the
 121 .B -a
 122 ,
 123 .B -i
 124 ,
 125 .B -p
 126 , and
 127 .B -s
 128 parameters. These parameters are cumulative. If none are given,
 129 debhelper programs default to acting on all packages listed in the control
 130 file.
 131 .P
 132 See
 133 .BR /usr/share/doc/debhelper/examples/rules.multi
 134 for an example of how to use this.
 135 .RE
 136 .TP
 137 .B Automatic generation of debian install scripts
 138 .RS
 139 Some debhelper commands will automatically generate parts of debian install
 140 scripts. If you want these automatically generated things included in your
 141 debian install scripts, then you need to add "#DEBHELPER#" to your scripts,
 142 in the place the code should be added. "#DEBHELPER#" will be replaced by
 143 any auto-generated code when you run dh_installdeb.
 144 .P
 145 All scripts that automatically generate code in this way let it be disabled
 146 by the -n parameter (see above).
 147 .P
 148 Note that the inserted code will be shell code, so you cannot directly use
 149 it in a perl script. If you would like to embed it into a perl script, here
 150 is one way to do that (note that I made sure that $1, $2, etc are set with
 151 the set command):
 152   my $temp="set -e\\nset -- @ARGV\\n" . << 'EOF';
 153   #DEBHELPER#
 154   EOF
 155   system ($temp) / 256 == 0
 156         or die "Problem with debhelper scripts: $!";
 157 .RE
 158 .TP
 159 .B Package build directories
 160 .RS
 161 By default, all debhelper programs assume that the temporary directory used
 162 for assembling the tree of files in a package is debian/<packagename>.
 163 .P
 164 Sometimes, you might want to use some other temporary directory. This is
 165 supported by the
 166 .B -P
 167 flag. For example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the
 168 temporary directory. Note that if you use -P, the debhelper programs can only
 169 be acting on a single package at a time. So if you have a package that builds
 170 many binary packages, you will need to use the -p flag to specify which
 171 binary package the debhelper program will act on.
 172 .RE
 173 .TP
 174 .B Debhelper compatability levels
 175 .RS
 176 From time to time, major non-backwards-compatabile changes need to be made
 177 to debhelper, to keep it clean and well-designed as needs change and its
 178 author gains more experience. To prevent such major changes from breaking
 179 existing packages, the DH_COMPAT environment variable was introduced.
 180 DH_COMPAT may be set to a number, to determine which major revision of
 181 debhelper should be used. There are currently 3:
 182 .TP
 183 .B V1
 184 Setting DH_COMPAT=1 (or leaving it unset) causes debhelper to act in
 185 compatability mode. It will use debian/tmp as the package tree
 186 directory for the first binary package listed in the control file, while using
 187 debian/<package> for all other packages listed in the control file.
 188 This mode is deprecated.
 189 .TP
 190 .B V2
 191 Setting DH_COMPAT=2 causes debhelper to consitently use debian/<package>
 192 as the package tree directory for every package that is built. This
 193 mode is currently set by default in all the example rules files, and you
 194 are encouraged to use it.
 195 .TP
 196 .B V3
 197 Setting DH_COMPAT=3 will make debhelper start using new v3 features as
 198 they are implemented. This will cause its behavior to change without
 199 notice, and so may break packages that use it. See the file
 200 "/usr/share/doc/debhelper/v3" for more information about planned
 201 changes.
 202 .RE
 203 .TP
 204 .B Doc directory symlinks
 205 .RS
 206 Sometimes it is useful to make a package not contain a /usr/share/doc/package
 207 directory at all, instead placing just a dangling symlink in the binary
 208 package, that points to some other doc directory. Policy says this is ok if
 209 your package depends on the package whose doc directory it uses. To
 210 accomplish this, just don't tell debhelper to install any documentation
 211 files into the package, and use dh_link to set up the symlink (or do it by
 212 hand), and debhelper should do the right thing: notice it is a dangling
 213 symlink and not try to install a copyright file or changelog.
 214 .RE
 215 .TP
 216 .B Other notes
 217 .RS
 218 In general, if any debhelper program needs a directory to exist under
 219 debian/, it will create it. I haven't bothered to document this in all the
 220 man pages, but for example, dh_installdeb knows to make debian/<foo>/DEBIAN/
 221 before trying to put files there, dh_installmenu knows you need a
 222 debian/<foo>/usr/lib/menu/ before installing the menu files, etc.
 223 .P
 224 Note that if you are generating a debian package that has arch-indep and
 225 arch-dependent portions, and you are using dh_movefiles to move the
 226 arch-indep files out of debian/tmp, you need to make sure that dh_movefiles
 227 does this even if only the arch-dependent package is being built (for
 228 ports to other architectures). I handle this in the example rules file
 229 "rules.multi" by calling dh_movefiles in the install target.
 230 .P
 231 Once your package uses debhelper to build, be sure to add
 232 debhelper to your Build-Depends line in debian/control.
 233 .RE
 234 .SH ENVIRONMENT
 235 .TP
 236 .I DH_VERBOSE
 237 Enables verbose mode.
 238 .TP
 239 .I DH_COMPAT
 240 Specifies what compatability level debhelper should run at. See above.
 241 .TP
 242 .I DH_NO_ACT
 243 Enables no-act mode.
 244 .TP
 245 .I DH_OPTIONS
 246 Anything in this variable will be prepended to the command line
 247 arguments of all debhelper commands. This in useful in some situations,
 248 for example, if you need to pass -p to all debhelper commands that will be
 249 run. If you use DH_OPTIONS, be sure to use "dh_testversion 1.1.17" - older
 250 debhelpers will ignore it and do things you don't want them to. One very
 251 good way to set DH_OPTIONS is by using "Target-specific Variable Values" in
 252 your debian/rules file. See the make documentation for details on doing this.
 253 .SH "SEE ALSO"
 254 .TP
 255 .BR /usr/share/doc/debhelper/examples/
 256 A set of example debian/rules files that use debhelper.
 257 .TP
 258 .BR http://kitenet.net/programs/debhelper/
 259 Debhelper web site.
 260 .SH AUTHOR
 261 Joey Hess <joeyh@debian.org>