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