man/deb-substvars.man

   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 .TH deb\-substvars 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  22 .nh
  23 .SH NAME
  24 deb\-substvars \- Debian source substitution variables
  25 .
  26 .SH SYNOPSIS
  27 substvars
  28 .
  29 .SH DESCRIPTION
  30 Before
  31 .BR dpkg\-source ", " dpkg\-gencontrol " and " dpkg\-genchanges
  32 write their control information (to the source control file
  33 .B .dsc
  34 for
  35 .B dpkg\-source
  36 and to standard output for
  37 .BR dpkg\-gencontrol " and " dpkg\-genchanges )
  38 they perform some variable substitutions on the output file.
  39
  40 A variable substitution has the form
  41 .BI ${ variable-name }\fR.
  42 Variable names consist of alphanumerics (a-zA-Z0-9), hyphens (-) and
  43 colons (:) and start with an alphanumeric, and are case-sensitive, even
  44 though they might refer to other entities which are case-preserving.
  45 Variable substitutions are performed repeatedly
  46 until none are left; the full text of the field after the substitution
  47 is rescanned to look for more substitutions.
  48
  49 After all the substitutions have been done each occurrence of the
  50 string
  51 .B ${}
  52 (which is not a legal substitution) is replaced with a
  53 .B $
  54 sign.
  55
  56 While variable substitution is done on all control fields, some of those
  57 fields are used and needed during the build when the substitution did not
  58 yet occur. That's why you can't use variables in the \fBPackage\fP,
  59 \fBSource\fP and \fBArchitecture\fP fields.
  60
  61 Variable substitution happens on the content of the fields after they have
  62 been parsed, thus if you want a variable to expand over multiple lines you
  63 do not have to include a space after the newline. This is done implicitly
  64 when the field is output. For example, if the variable
  65 \fB${Description}\fP is set to "foo is bar.${Newline}foo is
  66 great." and if you have the following field:
  67
  68  Description: foo application
  69   ${Description}
  70   .
  71   More text.
  72
  73 It will result in:
  74
  75  Description: foo application
  76   foo is bar.
  77   foo is great.
  78   .
  79   More text.
  80
  81 Variables can be set using the
  82 .B \-V
  83 common option. They can be also specified in the file
  84 .B debian/substvars
  85 (or whatever other file is specified using the
  86 .B \-T
  87 option). This file consists of lines of the form
  88 .IB name = value\fR.
  89 Trailing whitespace on each line, blank lines, and
  90 lines starting with a
  91 .B #
  92 symbol (comments) are ignored.
  93
  94 Additionally, the following standard variables are available:
  95 .TP
  96 .BI Arch
  97 The current host architecture (i.e. the architecture the package is being
  98 built for, the equivalent of \fBDEB_HOST_ARCH\fP).
  99 .TP
 100 .B source:Version
 101 The source package version (since dpkg 1.13.19).
 102 .TP
 103 .B source:Upstream\-Version
 104 The upstream source package version, including the Debian version epoch if
 105 any (since dpkg 1.13.19).
 106 .TP
 107 .B binary:Version
 108 The binary package version (which may differ from \fBsource:Version\fP in
 109 a binNMU for example; since dpkg 1.13.19).
 110 .TP
 111 .B Source\-Version
 112 The source package version (from the changelog file). This variable is now
 113 \fBobsolete\fP and emits an error when used as its meaning is different from
 114 its function, please use the \fBsource:Version\fP or \fBbinary:Version\fP as
 115 appropriate.
 116 .TP
 117 .B source:Synopsis
 118 The source package synopsis, extracted from the source stanza
 119 \fBDescription\fP field, if it exists (since dpkg 1.19.0).
 120 .TP
 121 .B source:Extended\-Description
 122 The source package extended description, extracted from the source stanza
 123 \fBDescription\fP field, if it exists (since dpkg 1.19.0).
 124 .TP
 125 .B Installed\-Size
 126 The approximate total size of the package's installed files. This value is
 127 copied into the corresponding control file field; setting it will modify
 128 the value of that field. If this variable is not set
 129 .B dpkg\-gencontrol
 130 will compute the default value by accumulating the size of each regular
 131 file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for
 132 any other filesystem object type.
 133
 134 \fBNote:\fP Take into account that this can only ever be an approximation,
 135 as the actual size used on the installed system will depend greatly on the
 136 filesystem used and its parameters, which might end up using either more
 137 or less space than the specified in this field.
 138 .TP
 139 .B Extra\-Size
 140 Additional disk space used when the package is installed. If this
 141 variable is set its value is added to that of the
 142 .B Installed\-Size
 143 variable (whether set explicitly or using the default value) before it
 144 is copied into the
 145 .B Installed\-Size
 146 control file field.
 147 .TP
 148 .BI S: fieldname
 149 The value of the source stanza field
 150 .I fieldname
 151 (which must be given in the canonical capitalisation; since dpkg 1.18.11).
 152 Setting these variables has no effect other than on places where they
 153 are expanded explicitly.
 154 These variables are only available when generating binary control files.
 155 .TP
 156 .BI F: fieldname
 157 The value of the output field
 158 .IR fieldname
 159 (which must be given in the canonical capitalisation). Setting these
 160 variables has no effect other than on places where they are expanded
 161 explicitly.
 162 .TP
 163 .B Format
 164 The
 165 .B .changes
 166 file format version generated by this version of the source packaging
 167 scripts. If you set this variable the contents of the
 168 .B Format
 169 field in the
 170 .B .changes
 171 file will change too.
 172 .TP
 173 .BR Newline ", " Space ", " Tab
 174 These variables each hold the corresponding character.
 175 .TP
 176 .BI shlibs: dependencyfield
 177 Variable settings with names of this form are generated by
 178 .BR dpkg\-shlibdeps .
 179 .TP
 180 .B dpkg:Upstream\-Version
 181 The upstream version of dpkg (since dpkg 1.13.19).
 182 .TP
 183 .B dpkg:Version
 184 The full version of dpkg (since dpkg 1.13.19).
 185 .LP
 186 If a variable is referred to but not defined it generates a warning
 187 and an empty value is assumed.
 188 .
 189 .SH FILES
 190 .TP
 191 .B debian/substvars
 192 List of substitution variables and values.
 193 .
 194 .SH SEE ALSO
 195 .ad l
 196 .BR dpkg (1),
 197 .BR dpkg\-genchanges (1),
 198 .BR dpkg\-gencontrol (1),
 199 .BR dpkg\-shlibdeps (1),
 200 .BR dpkg\-source (1).