man/deb-buildinfo.pod

   1 # dpkg manual page - deb-buildinfo(5)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2010 Russ Allbery <rra@debian.org>
   5 # Copyright © 2015-2016 Guillem Jover <guillem@debian.org>
   6 #
   7 # This is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 2 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  19
  20 =encoding utf8
  21
  22 =head1 NAME
  23
  24 deb-buildinfo - Debian build information file format
  25
  26 =head1 SYNOPSIS
  27
  28 I<filename>B<.buildinfo>
  29
  30 =head1 DESCRIPTION
  31
  32 Each Debian source package build can record the build information in
  33 a B<.buildinfo> control file, which contains a number of fields in
  34 L<deb822(5)> format.
  35
  36 Each field begins with a tag, such as
  37 B<Source>
  38 or
  39 B<Binary>
  40 (case insensitive), followed by a colon, and the body of the field
  41 (case sensitive unless stated otherwise).
  42 Fields are delimited only by field tags.
  43 In other words, field text may be multiple lines in length, but the
  44 installation tools will generally join lines when processing the body
  45 of the field (except in case of the multiline fields
  46 B<Binary-Only-Changes>, B<Installed-Build-Depends>, B<Environment>,
  47 B<Checksums-Md5>, B<Checksums-Sha1>
  48 and
  49 B<Checksums-Sha256>,
  50 see below).
  51
  52 The control data might be enclosed in an OpenPGP ASCII Armored signature,
  53 as specified in RFC4880.
  54
  55 The name of the B<.buildinfo> file will depend on the type of build and
  56 will be as specific as necessary but not more; the name will be:
  57
  58 =over
  59
  60 =item I<source-name>B<_>I<binary-version>B<_>I<arch>B<.buildinfo>
  61
  62 for a build that includes B<any>
  63
  64 =item I<source-name>B<_>I<binary-version>B<_>B<all.buildinfo>
  65
  66 otherwise for a build that includes B<all>
  67
  68 =item I<source-name>B<_>I<source-version>B<_>B<source.buildinfo>
  69
  70 otherwise for a build that includes B<source>
  71
  72 =back
  73
  74 =head1 FIELDS
  75
  76 =over
  77
  78 =item B<Format:> I<format-version> (required)
  79
  80 The value of this field declares the format version of the file.
  81 The syntax of the field value is a version number with a major and minor
  82 component.
  83 Backward incompatible changes to the format will bump the major version,
  84 and backward compatible changes (such as field additions) will bump the
  85 minor version.
  86 The current format version is B<1.0>.
  87
  88 =item B<Source:> I<source-name> [B<(>I<source-version>B<)>] (required)
  89
  90 The name of the source package.
  91 If the source version differs from the binary version, then the
  92 I<source-name> will be followed by a I<source-version> in parenthesis.
  93 This can happen when the build is for a binary-only non-maintainer upload.
  94
  95 =item B<Binary:> I<binary-package-list> (required in context)
  96
  97 This folded field is a space-separated list of binary packages built.
  98 If the build is source-only, then the field is omitted (since dpkg 1.20.0).
  99
 100 =item B<Architecture:> I<arch-list> (required)
 101
 102 This space-separated field lists the architectures of the files currently
 103 being built.
 104 Common architectures are B<amd64>, B<armel>, B<i386>, etc.
 105 Note that the B<all> value is meant for packages that are architecture
 106 independent.
 107 If the source for the package is also being built, the special entry
 108 B<source> is also present.
 109 Architecture wildcards must never be present in the list.
 110
 111 =item B<Version:> I<version-string> (required)
 112
 113 Typically, this is the original package's version number in whatever form
 114 the program's author uses.
 115 It may also include a Debian revision number (for non-native packages).
 116 The exact format and sorting algorithm are described in
 117 B<deb-version>(7).
 118
 119 =item B<Binary-Only-Changes:>
 120
 121 =item S< >I<changelog-entry>
 122
 123 This multiline field contains the concatenated text of the changelog
 124 entry for a binary-only non-maintainer upload (binNMU) if that is the case.
 125 To make this a valid multiline field empty lines are replaced with a
 126 single full stop (‘.’) and all lines are indented by one space
 127 character.
 128 The exact content depends on the changelog format.
 129
 130 =item B<Checksums-Md5:> (required)
 131
 132 =item B<Checksums-Sha1:> (required)
 133
 134 =item B<Checksums-Sha256:> (required)
 135
 136 =item S< >I<checksum> I<size> I<filename>
 137
 138 These multiline fields contain a list of files with a checksum and size
 139 for each one.
 140 These fields have the same syntax and differ only in the checksum algorithm
 141 used: MD5 for B<Checksums-Md5>, SHA-1 for B<Checksums-Sha1> and
 142 SHA-256 for B<Checksums-Sha256>.
 143
 144 The first line of the field value (the part on the same line as the field
 145 name followed by a colon) is always empty.
 146 The content of the field is expressed as continuation lines, one line per file.
 147 Each line consists of space-separated entries describing the file:
 148 the checksum, the file size, and the file name.
 149
 150 These fields list all files that make up the build.
 151
 152 =item B<Build-Origin:> I<name>
 153
 154 The name of the distribution this package is originating from.
 155
 156 =item B<Build-Architecture:> I<arch> (required)
 157
 158 The Debian architecture for the installation the packages is being built in.
 159 Common architectures are B<amd64>, B<armel>, B<i386>, etc.
 160
 161 =item B<Build-Date:> I<build-date>
 162
 163 The date the package was built.
 164 It must be in the same format as the date in a B<deb-changelog>(5)
 165 entry.
 166
 167 =item B<Build-Kernel-Version:> I<build-kernel-version>
 168
 169 The release and version (in an unspecified format) of the kernel running
 170 on the build system.
 171 This field is only going to be present if the builder has explicitly
 172 requested it, to avoid leaking possibly sensitive information.
 173
 174 =item B<Build-Path:> I<build-path>
 175
 176 The absolute build path, which correspond to the unpacked source tree.
 177 This field is only going to be present if the vendor has allowed it
 178 via some pattern match to avoid leaking possibly sensitive information.
 179
 180 On Debian and derivatives only build paths starting with I</build/>
 181 will emit this field.
 182
 183 =item B<Build-Tainted-By:>
 184
 185 =item S< >I<taint-reason-list>
 186
 187 This folded field contains a space-separated list of non-exhaustive reason
 188 tags (formed by alphanumeric and dash characters) which identify why the
 189 current build has been tainted (since dpkg 1.19.5).
 190
 191 On Debian and derivatives the following reason tags can be emitted:
 192
 193 =over
 194
 195 =item B<merged-usr-via-aliased-dirs>
 196
 197 The system has a merged I</usr> via aliased directories (previously known
 198 as B<merged-usr-via-symlinks>).
 199 This will confuse B<dpkg-query>, B<dpkg-statoverride>,
 200 B<dpkg-trigger>, B<update-alternatives> and any other tool using
 201 pathnames as keys into their databases, as it creates filesystem aliasing
 202 problems, and messes with the understanding of the filesystem that
 203 B<dpkg> has recorded in its database.
 204 For build systems that hardcode pathnames to specific binaries or libraries
 205 on the resulting artifacts, it can also produce packages that will be
 206 incompatible with non-/usr-merged filesystems.
 207
 208 =item B<usr-local-has-configs>
 209
 210 The system has configuration files under I</usr/local/etc>.
 211
 212 =item B<usr-local-has-includes>
 213
 214 The system has header files under I</usr/local/include>.
 215
 216 =item B<usr-local-has-programs>
 217
 218 The system has programs under I</usr/local/bin> or I</usr/local/sbin>.
 219
 220 =item B<usr-local-has-libraries>
 221
 222 The system has libraries, either static or shared under I</usr/local/lib>.
 223
 224 =item B<can-execute-cross-built-programs>
 225
 226 The system can execute cross built programs, either directly or via some
 227 emulation layer.
 228
 229 Since dpkg 1.21.10.
 230
 231 =back
 232
 233 =item B<Installed-Build-Depends:> (required)
 234
 235 =item S< >I<package-list>
 236
 237 The list of installed and configured packages that might affect the package
 238 build process.
 239
 240 The list consists of each package name, optionally arch-qualified for foreign
 241 architectures, with an exact version restriction, separated by commas.
 242
 243 The list includes all essential packages, packages listed in
 244 B<Build-Depends>, B<Build-Depends-Arch>, B<Build-Depends-Indep>
 245 source control fields, any vendor specific builtin dependencies, and all
 246 their recursive dependencies.
 247 On Debian and derivatives the dependency builtin is B<build-essential>.
 248
 249 For dependencies coming from the source control fields, all dependency
 250 alternatives and all providers of virtual packages depended on will be
 251 included.
 252
 253 =item B<Environment:>
 254
 255 =item S< >I<variable-list>
 256
 257 The list of environment variables that are known to affect the package build
 258 process, with each environment variable followed by an equal sign (‘=’)
 259 and the variable's quoted value, using double quotes (‘"’), and
 260 backslashes escaped (‘\\’).
 261
 262 =back
 263
 264 =head1 SEE ALSO
 265
 266 L<deb822(5)>,
 267 B<deb-changes>(5),
 268 B<deb-version>(7),
 269 B<dpkg-genbuildinfo>(1).