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 RFC9580.
  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 L<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, weak)
 131
 132 =item B<Checksums-Sha1:> (required, weak)
 133
 134 =item B<Checksums-Sha256:> (required, strong)
 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 B<Note>: The MD5 and SHA-1 checksums are considered weak,
 145 and should never be assumed to be sufficient for secure verification.
 146
 147 The first line of the field value (the part on the same line as the field
 148 name followed by a colon) is always empty.
 149 The content of the field is expressed as continuation lines, one line per file.
 150 Each line consists of space-separated entries describing the file:
 151 the checksum, the file size, and the file name.
 152
 153 These fields list all files that make up the build.
 154
 155 =item B<Build-Origin:> I<name>
 156
 157 The name of the distribution this package is originating from.
 158
 159 =item B<Build-Architecture:> I<arch> (required)
 160
 161 The Debian architecture for the installation the packages is being built in.
 162 Common architectures are B<amd64>, B<armel>, B<i386>, etc.
 163
 164 =item B<Build-Date:> I<build-date>
 165
 166 The date the package was built.
 167 It must be in the same format as the date in a L<deb-changelog(5)>
 168 entry.
 169
 170 =item B<Build-Kernel-Version:> I<build-kernel-version>
 171
 172 The release and version (in an unspecified format) of the kernel running
 173 on the build system.
 174 This field is only going to be present if the builder has explicitly
 175 requested it, to avoid leaking possibly sensitive information.
 176
 177 =item B<Build-Path:> I<build-path>
 178
 179 The absolute build path, which correspond to the unpacked source tree.
 180 This field is only going to be present if the vendor has allowed it
 181 via some pattern match to avoid leaking possibly sensitive information.
 182
 183 On Debian and derivatives only build paths starting with I</build/>
 184 will emit this field.
 185
 186 =item B<Build-Tainted-By:>
 187
 188 =item S< >I<taint-reason-list>
 189
 190 This folded field contains a space-separated list of non-exhaustive reason
 191 tags (formed by alphanumeric and dash characters) which identify why the
 192 current build has been tainted (since dpkg 1.19.5).
 193
 194 On Debian and derivatives the following reason tags can be emitted:
 195
 196 =over
 197
 198 =item B<merged-usr-via-aliased-dirs>
 199
 200 The system has a merged I</usr> via aliased directories (previously known
 201 as B<merged-usr-via-symlinks>).
 202 This will confuse B<dpkg-query>, B<dpkg-statoverride>,
 203 B<dpkg-trigger>, B<update-alternatives> and any other tool using
 204 pathnames as keys into their databases, as it creates filesystem aliasing
 205 problems, and messes with the understanding of the filesystem that
 206 B<dpkg> has recorded in its database.
 207 For build systems that hardcode pathnames to specific binaries or libraries
 208 on the resulting artifacts, it can also produce packages that will be
 209 incompatible with non-/usr-merged filesystems.
 210
 211 =item B<usr-local-has-configs>
 212
 213 The system has configuration files under I</usr/local/etc>.
 214
 215 =item B<usr-local-has-includes>
 216
 217 The system has header files under I</usr/local/include>.
 218
 219 =item B<usr-local-has-programs>
 220
 221 The system has programs under I</usr/local/bin> or I</usr/local/sbin>.
 222
 223 =item B<usr-local-has-libraries>
 224
 225 The system has libraries, either static or shared under I</usr/local/lib>.
 226
 227 =item B<can-execute-cross-built-programs>
 228
 229 The system can execute cross built programs, either directly or via some
 230 emulation layer.
 231
 232 Since dpkg 1.21.10.
 233
 234 =back
 235
 236 =item B<Installed-Build-Depends:> (required)
 237
 238 =item S< >I<package-list>
 239
 240 The list of installed and configured packages that might affect the package
 241 build process.
 242
 243 The list consists of each package name, optionally arch-qualified for foreign
 244 architectures, with an exact version restriction, separated by commas.
 245
 246 The list includes all essential packages, packages listed in
 247 B<Build-Depends>, B<Build-Depends-Arch>, B<Build-Depends-Indep>
 248 source control fields, any vendor specific builtin dependencies, and all
 249 their recursive dependencies.
 250 On Debian and derivatives the dependency builtin is B<build-essential>.
 251
 252 For dependencies coming from the source control fields, all dependency
 253 alternatives and all providers of virtual packages depended on will be
 254 included.
 255
 256 =item B<Environment:>
 257
 258 =item S< >I<variable-list>
 259
 260 The list of environment variables that are known to affect the package build
 261 process, with each environment variable followed by an equal sign (‘=’)
 262 and the variable's quoted value, using double quotes (‘"’), and
 263 backslashes escaped (‘\\’).
 264
 265 =back
 266
 267 =head1 SEE ALSO
 268
 269 L<deb822(5)>,
 270 L<deb-changes(5)>,
 271 L<deb-version(7)>,
 272 L<dpkg-genbuildinfo(1)>.