chiark - git - mdw - dpkg/blob - man/dpkg-deb.man

   1 .\" dpkg manual page - dpkg-deb(1)
   2 .\"
   3 .\" Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 .\" Copyright © 1999 Wichert Akkerman <wakkerma@debian.org>
   5 .\" Copyright © 2006 Frank Lichtenheld <djpig@debian.org>
   6 .\" Copyright © 2007-2015 Guillem Jover <guillem@debian.org>
   7 .\"
   8 .\" This is free software; you can redistribute it and/or modify
   9 .\" it under the terms of the GNU General Public License as published by
  10 .\" the Free Software Foundation; either version 2 of the License, or
  11 .\" (at your option) any later version.
  12 .\"
  13 .\" This is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public License
  19 .\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
  20 .
  21 .TH dpkg\-deb 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  22 .nh
  23 .SH NAME
  24 dpkg\-deb \- Debian package archive (.deb) manipulation tool
  25 .
  26 .SH SYNOPSIS
  27 .B dpkg\-deb
  28 .RI [ option "...] " command
  29 .
  30 .SH DESCRIPTION
  31 .B dpkg\-deb
  32 packs, unpacks and provides information about Debian archives.
  33 .PP
  34 Use
  35 .B dpkg
  36 to install and remove packages from your system.
  37 .PP
  38 You can also invoke
  39 .B dpkg\-deb
  40 by calling
  41 .B dpkg
  42 with whatever options you want to pass to
  43 .BR dpkg\-deb ". " dpkg
  44 will spot that you wanted
  45 .B dpkg\-deb
  46 and run it for you.
  47 .PP
  48 For most commands taking an input archive argument, the archive can be
  49 read from standard input if the archive name is given as a single minus
  50 character («\fB\-\fP»); otherwise lack of support will be documented in
  51 their respective command description.
  52 .
  53 .SH COMMANDS
  54 .TP
  55 .BR \-b ", " \-\-build " \fIbinary-directory\fP [\fIarchive\fP|\fIdirectory\fP]"
  56 Creates a debian archive from the filesystem tree stored in
  57 .IR binary-directory ". " binary-directory
  58 must have a
  59 .B DEBIAN
  60 subdirectory, which contains the control information files such
  61 as the control file itself. This directory will
  62 .I not
  63 appear in the binary package's filesystem archive, but instead
  64 the files in it will be put in the binary package's control
  65 information area.
  66
  67 Unless you specify
  68 .BR \-\-nocheck ", " dpkg\-deb "
  69 will read
  70 .B DEBIAN/control
  71 and parse it. It will check the file for syntax errors and other problems,
  72 and display the name of the binary package being built.
  73 .B dpkg\-deb
  74 will also check the permissions of the maintainer scripts and other
  75 files found in the
  76 .B DEBIAN
  77 control information directory.
  78
  79 If no
  80 .I archive
  81 is specified then
  82 .B dpkg\-deb
  83 will write the package into the file
  84 .IR binary-directory \fB.deb\fR.
  85
  86 If the archive to be created already exists it will be overwritten.
  87
  88 If the second argument is a directory then
  89 .B dpkg\-deb
  90 will write to the file
  91 .IB directory / package _ version _ arch .deb.
  92 When a target directory is specified, rather than a file, the
  93 .B \-\-nocheck
  94 option may not be used (since
  95 .B dpkg\-deb
  96 needs to read and parse the package control file to determine which
  97 filename to use).
  98 .TP
  99 .BR \-I ", " \-\-info " \fIarchive\fP [\fIcontrol-file-name\fP...]"
 100 Provides information about a binary package archive.
 101
 102 If no
 103 .IR control-file-name s
 104 are specified then it will print a summary of the contents of the
 105 package as well as its control file.
 106
 107 If any
 108 .IR control-file-name s
 109 are specified then
 110 .B dpkg\-deb
 111 will print them in the order they were specified; if any of the
 112 components weren't present it will print an error message to stderr
 113 about each one and exit with status 2.
 114 .TP
 115 .BR \-W ", " \-\-show " \fIarchive\fP"
 116 Provides information about a binary package archive in the format
 117 specified by the
 118 .B \-\-showformat
 119 argument. The default format displays the package's name and version
 120 on one line, separated by a tabulator.
 121 .TP
 122 .BR \-f ", " \-\-field " \fIarchive\fP [\fIcontrol-field-name\fP...]"
 123 Extracts control file information from a binary package archive.
 124
 125 If no
 126 .IR control-field-name s
 127 are specified then it will print the whole control file.
 128
 129 If any are specified then
 130 .B dpkg\-deb
 131 will print their contents, in the order in which they appear in the
 132 control file. If more than one
 133 .IR control-field-name
 134 is specified then
 135 .B dpkg\-deb
 136 will precede each with its field name (and a colon and space).
 137
 138 No errors are reported for fields requested but not found.
 139 .TP
 140 .BR \-c ", " \-\-contents " \fIarchive\fP"
 141 Lists the contents of the filesystem tree archive portion of the
 142 package archive. It is currently produced in the format generated by
 143 .BR tar 's
 144 verbose listing.
 145 .TP
 146 .BR \-x ", " \-\-extract " \fIarchive directory\fP"
 147 Extracts the filesystem tree from a package archive into the specified
 148 directory.
 149
 150 Note that extracting a package to the root directory will
 151 .I not
 152 result in a correct installation! Use
 153 .B dpkg
 154 to install packages.
 155
 156 .I directory
 157 (but not its parents) will be created if necessary, and its permissions
 158 modified to match the contents of the package.
 159 .TP
 160 .BR \-X ", " \-\-vextract " \fIarchive directory\fP"
 161 Is like
 162 .BR \-\-extract " (" \-x ")"
 163 with
 164 .BR \-\-verbose " (" \-v ")"
 165 which prints a listing of the files extracted as it goes.
 166 .TP
 167 .BR \-R ", " \-\-raw\-extract " \fIarchive directory\fP"
 168 Extracts the filesystem tree from a package archive into a specified
 169 directory, and the control information files into a
 170 .B DEBIAN
 171 subdirectory of the specified directory (since dpkg 1.16.1).
 172
 173 The target directory (but not its parents) will be created if necessary.
 174
 175 The input archive is not (currently) processed sequentially, so reading
 176 it from standard input («\fB-\fP») is \fBnot\fP supported.
 177 .TP
 178 .BR \-\-ctrl\-tarfile " \fIarchive\fP"
 179 Extracts the control data from a binary package and sends it to standard
 180 output in
 181 .B tar
 182 format (since dpkg 1.17.14). Together with
 183 .BR tar (1)
 184 this can be used to extract a particular control file from a package archive.
 185 The input archive will always be processed sequentially.
 186 .TP
 187 .BR \-\-fsys\-tarfile " \fIarchive\fP"
 188 Extracts the filesystem tree data from a binary package and sends it
 189 to standard output in
 190 .B tar
 191 format. Together with
 192 .BR tar (1)
 193 this can be used to extract a particular file from a package archive.
 194 The input archive will always be processed sequentially.
 195 .TP
 196 .BR \-e ", " \-\-control " \fIarchive\fP [\fIdirectory\fP]"
 197 Extracts the control information files from a package archive into the
 198 specified directory.
 199
 200 If no directory is specified then a subdirectory
 201 .B DEBIAN
 202 in the current directory is used.
 203
 204 The target directory (but not its parents) will be created if
 205 necessary.
 206 .TP
 207 .BR \-? ", " \-\-help
 208 Show the usage message and exit.
 209 .TP
 210 .BR \-\-version
 211 Show the version and exit.
 212 .
 213 .SH OPTIONS
 214 .TP
 215 \fB\-\-showformat=\fP\fIformat\fR
 216 This option is used to specify the format of the output \fB\-\-show\fP
 217 will produce. The format is a string that will be output for each package
 218 listed.
 219
 220 The string may reference any status field using the
 221 “${\fIfield-name\fR}” form, a list of the valid fields can be easily
 222 produced using
 223 .B \-I
 224 on the same package. A complete explanation of the formatting options
 225 (including escape sequences and field tabbing) can be found in the
 226 explanation of the \fB\-\-showformat\fP option in
 227 .BR dpkg\-query (1).
 228
 229 The default for this field is “${Package}\\t${Version}\\n”.
 230 .TP
 231 .BI \-z compress-level
 232 Specify which compression level to use on the compressor backend, when
 233 building a package (default is 9 for gzip, 6 for xz).
 234 The accepted values are 0-9 with: 0 being mapped to compressor none for gzip.
 235 Before dpkg 1.16.2 level 0 was equivalent to compressor none for all
 236 compressors.
 237 .TP
 238 .BI \-S compress-strategy
 239 Specify which compression strategy to use on the compressor backend, when
 240 building a package (since dpkg 1.16.2). Allowed values are \fBnone\fP (since
 241 dpkg 1.16.4), \fBfiltered\fP, \fBhuffman\fP, \fBrle\fP and \fBfixed\fP for
 242 gzip (since dpkg 1.17.0) and \fBextreme\fP for xz.
 243 .TP
 244 .BI \-Z compress-type
 245 Specify which compression type to use when building a package.
 246 Allowed values are \fBgzip\fP, \fBxz\fP (since dpkg 1.15.6),
 247 and \fBnone\fP (default is \fBxz\fP).
 248 .TP
 249 .B \-\-uniform\-compression
 250 Specify that the same compression parameters should be used for all archive
 251 members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6).
 252 Otherwise only the
 253 \fBdata.tar\fP member will use those parameters. The only supported
 254 compression types allowed to be uniformly used are \fBnone\fP, \fBgzip\fP
 255 and \fBxz\fP.
 256 .TP
 257 .BI \-\-deb\-format= format
 258 Set the archive format version used when building (since dpkg 1.17.0).
 259 Allowed values are \fB2.0\fP for the new format, and \fB0.939000\fP
 260 for the old one (default is \fB2.0\fP).
 261
 262 The old archive format is less easily parsed by non-Debian tools and is
 263 now obsolete; its only use is when building packages to be parsed by
 264 versions of dpkg older than 0.93.76 (September 1995), which was released
 265 as i386 a.out only.
 266 .TP
 267 .BR \-\-nocheck
 268 Inhibits
 269 .BR "dpkg\-deb \-\-build" 's
 270 usual checks on the proposed contents of an archive. You can build
 271 any archive you want, no matter how broken, this way.
 272 .TP
 273 .BR \-v ", " \-\-verbose
 274 Enables verbose output (since dpkg 1.16.1).
 275 This currently only affects \fB\-\-extract\fP making it behave like
 276 \fB\-\-vextract\fP.
 277 .TP
 278 .BR \-D ", " \-\-debug
 279 Enables debugging output. This is not very interesting.
 280 .
 281 .SH EXIT STATUS
 282 .TP
 283 .B 0
 284 The requested action was successfully performed.
 285 .TP
 286 .B 2
 287 Fatal or unrecoverable error due to invalid command-line usage, or
 288 interactions with the system, such as accesses to the database,
 289 memory allocations, etc.
 290 .
 291 .SH ENVIRONMENT
 292 .TP
 293 .B TMPDIR
 294 If set, \fBdpkg\-deb\fP will use it as the directory in which to create
 295 temporary files and directories.
 296 .TP
 297 .B SOURCE_DATE_EPOCH
 298 If set, it will be used as the timestamp (as seconds since the epoch) in
 299 the \fBdeb\fP(5)'s \fBar\fP(5) container and used to clamp the mtime in
 300 the \fBtar\fP(5) file entries.
 301 .
 302 .SH NOTES
 303 Do not attempt to use just
 304 .B dpkg\-deb
 305 to install software! You must use
 306 .B dpkg
 307 proper to ensure that all the files are correctly placed and the
 308 package's scripts run and its status and contents recorded.
 309 .
 310 .SH BUGS
 311 .B dpkg\-deb \-I
 312 .IB package1 .deb
 313 .IB package2 .deb
 314 does the wrong thing.
 315
 316 There is no authentication on
 317 .B .deb
 318 files; in fact, there isn't even a straightforward checksum.
 319 (Higher level tools like APT support authenticating \fB.deb\fP packages
 320 retrieved from a given repository, and most packages nowadays provide an
 321 md5sum control file generated by debian/rules. Though this is not directly
 322 supported by the lower level tools.)
 323 .
 324 .SH SEE ALSO
 325 .BR deb (5),
 326 .BR deb\-control (5),
 327 .BR dpkg (1),
 328 .BR dselect (1).