man/deb-substvars.pod

   1 # dpkg manual page - deb-substvars(5)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
   5 # Copyright © 2006-2009,2012-2015 Guillem Jover <guillem@debian.org>
   6 # Copyright © 2009-2010 Raphaël Hertzog <hertzog@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 =encoding utf8
  22
  23 =head1 NAME
  24
  25 deb-substvars - Debian source substitution variables
  26
  27 =head1 SYNOPSIS
  28
  29 B<debian/substvars>, B<debian/>I<binary-package>B<.substvars>, variables
  30
  31 =head1 DESCRIPTION
  32
  33 Before
  34 B<dpkg-source>, B<dpkg-gencontrol> and B<dpkg-genchanges>
  35 write their control information (to the source control file
  36 B<.dsc>
  37 for
  38 B<dpkg-source>
  39 and to standard output for
  40 B<dpkg-gencontrol> and B<dpkg-genchanges>)
  41 they perform some variable substitutions on the output file.
  42
  43 =head2 Variable Syntax
  44
  45 A variable substitution has the form
  46 B<${>I<variable-name>B<}>.
  47 Variable names consist of alphanumerics (a-zA-Z0-9), hyphens (-) and
  48 colons (:) and start with an alphanumeric, and are case-sensitive, even
  49 though they might refer to other entities which are case-preserving.
  50 Variable substitutions are performed repeatedly
  51 until none are left; the full text of the field after the substitution
  52 is rescanned to look for more substitutions.
  53
  54 =head2 File Syntax
  55
  56 Substitution variables can be specified in a file.
  57 These files consist of lines of the form I<name>B<=>I<value> or
  58 I<name>B<?=>I<value>.
  59 The B<=> operator assigns a normal substitution variable, while the B<?=>
  60 operator (since dpkg 1.21.8) assigns an optional substitution variable
  61 which will emit no warnings even if unused.
  62 Trailing whitespace on each line, blank lines, and lines starting with a
  63 B<#> symbol (comments) are ignored.
  64
  65 =head2 Substitution
  66
  67 Variables can be set using the B<-V> common option.
  68 They can be also specified in the file B<debian/substvars>
  69 (or whatever other file is specified using the B<-T> common option).
  70
  71 After all the substitutions have been done each occurrence of the
  72 string
  73 B<${}>
  74 (which is not an actual substitution variable) is replaced with a
  75 B<$>
  76 sign.
  77 This can be used as an escape sequence such as B<${}{>I<VARIABLE>B<}> which
  78 will end up as B<${>I<VARIABLE>B<}> on the output.
  79
  80 If a variable is referred to but not defined it generates a warning
  81 and an empty value is assumed.
  82
  83 While variable substitution is done on all control fields, some of those
  84 fields are used and needed during the build when the substitution did not
  85 yet occur. That's why you can't use variables in the B<Package>,
  86 B<Source> and B<Architecture> fields.
  87
  88 Variable substitution happens on the content of the fields after they have
  89 been parsed, thus if you want a variable to expand over multiple lines you
  90 do not have to include a space after the newline. This is done implicitly
  91 when the field is output. For example, if the variable
  92 B<${Description}> is set to "foo is bar.${Newline}foo is
  93 great." and if you have the following field:
  94
  95  Description: foo application
  96   ${Description}
  97   .
  98   More text.
  99
 100 It will result in:
 101
 102  Description: foo application
 103   foo is bar.
 104   foo is great.
 105   .
 106   More text.
 107
 108 =head2 Built-in Variable
 109
 110 Additionally, the following standard variables are always available:
 111
 112 =over
 113
 114 =item B<Arch>
 115
 116 The current host architecture (i.e. the architecture the package is being
 117 built for, the equivalent of B<DEB_HOST_ARCH>).
 118
 119 =item B<vendor:Name>
 120
 121 The current vendor name (since dpkg 1.20.0).
 122 This value comes from the B<Vendor> field for the current vendor's origin
 123 file, as B<dpkg-vendor>(1) would retrieve it.
 124
 125 =item B<vendor:Id>
 126
 127 The current vendor ID (since dpkg 1.20.0).
 128 This is just the lowercase variant of B<vendor:Name>.
 129
 130 =item B<source:Version>
 131
 132 The source package version (since dpkg 1.13.19).
 133
 134 =item B<source:Upstream-Version>
 135
 136 The upstream source package version, including the Debian version epoch if
 137 any (since dpkg 1.13.19).
 138
 139 =item B<binary:Version>
 140
 141 The binary package version (which may differ from B<source:Version> in
 142 a binNMU for example; since dpkg 1.13.19).
 143
 144 =item B<Source-Version>
 145
 146 The source package version (from the changelog file). This variable is now
 147 B<obsolete> and emits an error when used as its meaning is different from
 148 its function, please use the B<source:Version> or B<binary:Version> as
 149 appropriate.
 150
 151 =item B<source:Synopsis>
 152
 153 The source package synopsis, extracted from the source stanza
 154 B<Description> field, if it exists (since dpkg 1.19.0).
 155
 156 =item B<source:Extended-Description>
 157
 158 The source package extended description, extracted from the source stanza
 159 B<Description> field, if it exists (since dpkg 1.19.0).
 160
 161 =item B<Installed-Size>
 162
 163 The approximate total size of the package's installed files. This value is
 164 copied into the corresponding control file field; setting it will modify
 165 the value of that field. If this variable is not set
 166 B<dpkg-gencontrol>
 167 will compute the default value by accumulating the size of each regular
 168 file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for
 169 any other filesystem object type.
 170 With hardlinks only being counted once as a regular file.
 171
 172 B<Note>: Take into account that this can only ever be an approximation,
 173 as the actual size used on the installed system will depend greatly on the
 174 filesystem used and its parameters, which might end up using either more
 175 or less space than the specified in this field.
 176
 177 =item B<Extra-Size>
 178
 179 Additional disk space used when the package is installed. If this
 180 variable is set its value is added to that of the
 181 B<Installed-Size>
 182 variable (whether set explicitly or using the default value) before it
 183 is copied into the
 184 B<Installed-Size>
 185 control file field.
 186
 187 =item B<S:>I<fieldname>
 188
 189 The value of the source stanza field
 190 I<fieldname>
 191 (which must be given in the canonical capitalization; since dpkg 1.18.11).
 192 Setting these variables has no effect other than on places where they
 193 are expanded explicitly.
 194 These variables are only available when generating binary control files.
 195
 196 =item B<F:>I<fieldname>
 197
 198 The value of the output field
 199 I<fieldname>
 200 (which must be given in the canonical capitalization). Setting these
 201 variables has no effect other than on places where they are expanded
 202 explicitly.
 203
 204 =item B<Format>
 205
 206 The
 207 B<.changes>
 208 file format version generated by this version of the source packaging
 209 scripts. If you set this variable the contents of the
 210 B<Format>
 211 field in the
 212 B<.changes>
 213 file will change too.
 214
 215 =item B<Newline>, B<Space>, B<Tab>
 216
 217 These variables each hold the corresponding character.
 218
 219 =item B<shlibs:>I<dependencyfield>
 220
 221 Variable settings with names of this form are generated by
 222 B<dpkg-shlibdeps>.
 223
 224 =item B<dpkg:Upstream-Version>
 225
 226 The upstream version of dpkg (since dpkg 1.13.19).
 227
 228 =item B<dpkg:Version>
 229
 230 The full version of dpkg (since dpkg 1.13.19).
 231
 232 =back
 233
 234 =head1 FILES
 235
 236 =over
 237
 238 =item B<debian/substvars>
 239
 240 List of substitution variables and values.
 241
 242 =back
 243
 244 =head1 SEE ALSO
 245
 246 B<dpkg>(1),
 247 B<dpkg-vendor>(1),
 248 B<dpkg-genchanges>(1),
 249 B<dpkg-gencontrol>(1),
 250 B<dpkg-shlibdeps>(1),
 251 B<dpkg-source>(1).