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