1deb-substvars(5) dpkg suite deb-substvars(5)
2
6 deb-substvars - Debian source substitution variables
7
9 debian/substvars, debian/binary-package.substvars, variables
10
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 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 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 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 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 If a variable is referred to but not defined it generates a warning and
45 an empty value is assumed.
46 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 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 Description: foo application
60 ${Description}
61 .
62 More text.
63 It will result in:
65 Description: foo application
67 foo is bar.
68 foo is great.
69 .
70 More text.
71 Built-in Variable
73 Additionally, the following standard variables are always available:
74 Arch
76 The current host architecture (i.e. the architecture the package is
77 being built for, the equivalent of DEB_HOST_ARCH).
78 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 vendor:Id
85 The current vendor ID (since dpkg 1.20.0). This is just the
86 lowercase variant of vendor:Name.
87 source:Version
89 The source package version (since dpkg 1.13.19).
90 source:Upstream-Version
92 The upstream source package version, including the Debian version
93 epoch if any (since dpkg 1.13.19).
94 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 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 source:Synopsis
106 The source package synopsis, extracted from the source stanza
107 Description field, if it exists (since dpkg 1.19.0).
108 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 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 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 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 S:fieldname
135 The value of the source stanza field fieldname (which must be given
136 in the canonical capitalisation; 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 F:fieldname
142 The value of the output field fieldname (which must be given in the
143 canonical capitalisation). Setting these variables has no effect
144 other than on places where they are expanded explicitly.
145 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 Newline, Space, Tab
152 These variables each hold the corresponding character.
153 shlibs:dependencyfield
155 Variable settings with names of this form are generated by dpkg-
156 shlibdeps.
157 dpkg:Upstream-Version
159 The upstream version of dpkg (since dpkg 1.13.19).
160 dpkg:Version
162 The full version of dpkg (since dpkg 1.13.19).
163
165 debian/substvars
166 List of substitution variables and values.
167
169 dpkg(1), dpkg-vendor(1), dpkg-genchanges(1), dpkg-gencontrol(1), dpkg-
170 shlibdeps(1), dpkg-source(1).
1711.21.8 2022-05-25 deb-substvars(5)