man/dpkg-build-api.pod

   1 # dpkg manual page - dpkg-build-api(7)
   2 #
   3 # Copyright © 2021-2023 Guillem Jover <guillem@debian.org>
   4 #
   5 # This is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  17
  18 =encoding utf8
  19
  20 =head1 NAME
  21
  22 dpkg-build-api - source package dpkg build API level
  23
  24 =head1 SYNOPSIS
  25
  26  Build-Depends:
  27   dpkg-build-api (= 1),
  28
  29 =head1 DESCRIPTION
  30
  31 The source package dpkg build API level, defines a versioned interface for
  32 source packages, where each API level provides specific behaviors and
  33 guarantees.
  34
  35 These interfaces can then be adopted by packages in a gradual way,
  36 and phased out more easily than with global behavior changes.
  37
  38 The declaration of this API level is done through build-dependencies, in
  39 one of B<Build-Depends>, B<Build-Depends-Indep> or B<Build-Depends-Arch>,
  40 or via the environment variable B<DPKG_BUILD_API>, which will override these
  41 if both are present, and might emit a warning in case they are different.
  42
  43 =head1 API LEVELS
  44
  45 =over
  46
  47 =item v2
  48
  49 This level is still under development, and cannot be declared via
  50 build-dependencies.
  51
  52 =item v1
  53
  54 This is the recommended level.
  55 Since dpkg 1.22.0.
  56
  57 Changes from v0 are:
  58
  59 =over
  60
  61 =item *
  62
  63 B<dpkg-shlibdeps> no longer uses the B<LD_LIBRARY_PATH> environment variable.
  64 The B<-l> option should be used instead.
  65
  66 =item *
  67
  68 B<dpkg-buildpackage> defaults to B<Rules-Requires-Root> value B<no>.
  69 To restore the B<v0> behavior B<Rules-Requires-Root> should be set to
  70 B<binary-targets>.
  71
  72 =item *
  73
  74 B<dpkg-buildpackage> expects all required F<debian/rules> targets to be
  75 supported and no longer has backwards compatibility fallback code.
  76 The required targets are B<clean>, B<build>, B<build-indep>, B<build-arch>,
  77 B<binary-indep> and B<binary-arch>.
  78
  79 =item *
  80
  81 B<vendor.mk> defaults to using B<dpkg_vendor_derives_from_v1> for the
  82 B<dpkg_vendor_derives_from> macro.
  83 To restore the B<v0> behavior set B<dpkg_vendor_derives_from> to
  84 B<dpkg_vendor_derives_from_v0>.
  85
  86 =item *
  87
  88 B<default.mk> defaults to including B<buildtools.mk>.
  89
  90 =back
  91
  92 =item v0
  93
  94 This is the current global level, equivalent to not specifying one.
  95 The interfaces and behaviors provided are subject to the normal global
  96 interface updates, which tend to require longer deprecation cycles and/or
  97 coordinated transitions.
  98
  99 =back
 100
 101 =head1 SEE ALSO
 102
 103 L<deb-src-control(5)>.