1deb-substvars(5)                  dpkg suite                  deb-substvars(5)
2
3
4

NAME

6       deb-substvars - Debian source substitution variables
7

SYNOPSIS

9       debian/substvars, debian/binary-package.substvars, variables
10

DESCRIPTION

12       Before dpkg-source, dpkg-gencontrol and dpkg-genchanges write their
13       control information (to the source control file .dsc for dpkg-source
14       and to standard output for dpkg-gencontrol and dpkg-genchanges) they
15       perform some variable substitutions on the output file.
16
17   Variable Syntax
18       A variable substitution has the form ${variable-name}.  Variable names
19       consist of alphanumerics (a-zA-Z0-9), hyphens (-) and colons (:) and
20       start with an alphanumeric, and are case-sensitive, even though they
21       might refer to other entities which are case-preserving.  Variable
22       substitutions are performed repeatedly until none are left; the full
23       text of the field after the substitution is rescanned to look for more
24       substitutions.
25
26   File Syntax
27       Substitution variables can be specified in a file.  These files consist
28       of lines of the form name=value or name?=value.  The = operator assigns
29       a normal substitution variable, while the ?= operator (since dpkg
30       1.21.8) assigns an optional substitution variable which will emit no
31       warnings even if unused.  Trailing whitespace on each line, blank
32       lines, and lines starting with a # symbol (comments) are ignored.
33
34   Substitution
35       Variables can be set using the -V common option.  They can be also
36       specified in the file debian/substvars (or whatever other file is
37       specified using the -T common option).
38
39       After all the substitutions have been done each occurrence of the
40       string ${} (which is not an actual substitution variable) is replaced
41       with a $ sign.  This can be used as an escape sequence such as
42       ${}{VARIABLE} which will end up as ${VARIABLE} on the output.
43
44       If a variable is referred to but not defined it generates a warning and
45       an empty value is assumed.
46
47       While variable substitution is done on all control fields, some of
48       those fields are used and needed during the build when the substitution
49       did not yet occur. That's why you can't use variables in the Package,
50       Source and Architecture fields.
51
52       Variable substitution happens on the content of the fields after they
53       have been parsed, thus if you want a variable to expand over multiple
54       lines you do not have to include a space after the newline. This is
55       done implicitly when the field is output. For example, if the variable
56       ${Description} is set to "foo is bar.${Newline}foo is great." and if
57       you have the following field:
58
59        Description: foo application
60         ${Description}
61         .
62         More text.
63
64       It will result in:
65
66        Description: foo application
67         foo is bar.
68         foo is great.
69         .
70         More text.
71
72   Built-in Variable
73       Additionally, the following standard variables are always available:
74
75       Arch
76           The current host architecture (i.e. the architecture the package is
77           being built for, the equivalent of DEB_HOST_ARCH).
78
79       vendor:Name
80           The current vendor name (since dpkg 1.20.0).  This value comes from
81           the Vendor field for the current vendor's origin file, as dpkg-
82           vendor(1) would retrieve it.
83
84       vendor:Id
85           The current vendor ID (since dpkg 1.20.0).  This is just the
86           lowercase variant of vendor:Name.
87
88       source:Version
89           The source package version (since dpkg 1.13.19).
90
91       source:Upstream-Version
92           The upstream source package version, including the Debian version
93           epoch if any (since dpkg 1.13.19).
94
95       binary:Version
96           The binary package version (which may differ from source:Version in
97           a binNMU for example; since dpkg 1.13.19).
98
99       Source-Version
100           The source package version (from the changelog file). This variable
101           is now obsolete and emits an error when used as its meaning is
102           different from its function, please use the source:Version or
103           binary:Version as appropriate.
104
105       source:Synopsis
106           The source package synopsis, extracted from the source stanza
107           Description field, if it exists (since dpkg 1.19.0).
108
109       source:Extended-Description
110           The source package extended description, extracted from the source
111           stanza Description field, if it exists (since dpkg 1.19.0).
112
113       Installed-Size
114           The approximate total size of the package's installed files. This
115           value is copied into the corresponding control file field; setting
116           it will modify the value of that field. If this variable is not set
117           dpkg-gencontrol will compute the default value by accumulating the
118           size of each regular file and symlink rounded to 1 KiB used units,
119           and a baseline of 1 KiB for any other filesystem object type.  With
120           hardlinks only being counted once as a regular file.
121
122           Note: Take into account that this can only ever be an
123           approximation, as the actual size used on the installed system will
124           depend greatly on the filesystem used and its parameters, which
125           might end up using either more or less space than the specified in
126           this field.
127
128       Extra-Size
129           Additional disk space used when the package is installed. If this
130           variable is set its value is added to that of the Installed-Size
131           variable (whether set explicitly or using the default value) before
132           it is copied into the Installed-Size control file field.
133
134       S:fieldname
135           The value of the source stanza field fieldname (which must be given
136           in the canonical capitalization; since dpkg 1.18.11).  Setting
137           these variables has no effect other than on places where they are
138           expanded explicitly.  These variables are only available when
139           generating binary control files.
140
141       F:fieldname
142           The value of the output field fieldname (which must be given in the
143           canonical capitalization). Setting these variables has no effect
144           other than on places where they are expanded explicitly.
145
146       Format
147           The .changes file format version generated by this version of the
148           source packaging scripts. If you set this variable the contents of
149           the Format field in the .changes file will change too.
150
151       Newline, Space, Tab
152           These variables each hold the corresponding character.
153
154       shlibs:dependencyfield
155           Variable settings with names of this form are generated by dpkg-
156           shlibdeps.
157
158       dpkg:Upstream-Version
159           The upstream version of dpkg (since dpkg 1.13.19).
160
161       dpkg:Version
162           The full version of dpkg (since dpkg 1.13.19).
163

FILES

165       debian/substvars
166           List of substitution variables and values.
167

SEE ALSO

169       dpkg(1), dpkg-vendor(1), dpkg-genchanges(1), dpkg-gencontrol(1), dpkg-
170       shlibdeps(1), dpkg-source(1).
171
172
173
1741.21.21                           2023-02-25                  deb-substvars(5)
Impressum