262 lines
7.5 KiB
Text
262 lines
7.5 KiB
Text
# dpkg manual page - deb-substvars(5)
|
|
#
|
|
# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
|
|
# Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
|
|
# Copyright © 2006-2009,2012-2015 Guillem Jover <guillem@debian.org>
|
|
# Copyright © 2009-2010 Raphaël Hertzog <hertzog@debian.org>
|
|
#
|
|
# This is free software; you can redistribute it and/or modify
|
|
# it under the terms of the GNU General Public License as published by
|
|
# the Free Software Foundation; either version 2 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
deb-substvars - Debian source substitution variables
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<debian/substvars>, B<debian/>I<binary-package>B<.substvars>, variables
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Before
|
|
B<dpkg-source>, B<dpkg-gencontrol> and B<dpkg-genchanges>
|
|
write their control information (to the source control file
|
|
B<.dsc>
|
|
for
|
|
B<dpkg-source>
|
|
and to standard output for
|
|
B<dpkg-gencontrol> and B<dpkg-genchanges>)
|
|
they perform some variable substitutions on the output file.
|
|
|
|
=head2 Variable Syntax
|
|
|
|
A variable substitution has the form
|
|
B<${>I<variable-name>B<}>.
|
|
Variable names consist of alphanumerics (a-zA-Z0-9), hyphens (-) and
|
|
colons (:) and start with an alphanumeric, and are case-sensitive, even
|
|
though they might refer to other entities which are case-preserving.
|
|
Variable substitutions are performed repeatedly
|
|
until none are left; the full text of the field after the substitution
|
|
is rescanned to look for more substitutions.
|
|
|
|
=head2 File Syntax
|
|
|
|
Substitution variables can be specified in a file.
|
|
These files consist of lines of the form I<name>B<=>I<value>,
|
|
I<name>B<?=>I<value>, or
|
|
I<name>B<!=>I<value>.
|
|
The B<=> operator assigns a normal substitution variable,
|
|
the B<?=> operator (since dpkg 1.21.8) assigns an optional substitution
|
|
variable which will emit no warnings even if unused,
|
|
and the B<!=> operator (since dpkg 1.22.7) assigns a required substitution
|
|
variable which will error out if unused.
|
|
Trailing whitespace on each line, blank lines, and lines starting with a
|
|
B<#> symbol (comments) are ignored.
|
|
|
|
=head2 Substitution
|
|
|
|
Variables can be set using the B<-V> common option.
|
|
They can be also specified in the file B<debian/substvars>
|
|
(or whatever other file is specified using the B<-T> common option).
|
|
|
|
After all the substitutions have been done each occurrence of the
|
|
string
|
|
B<${}>
|
|
(which is not an actual substitution variable) is replaced with a
|
|
B<$>
|
|
sign.
|
|
This can be used as an escape sequence such as B<${}{>I<VARIABLE>B<}> which
|
|
will end up as B<${>I<VARIABLE>B<}> on the output.
|
|
|
|
If a variable is referred to but not defined it generates a warning
|
|
and an empty value is assumed.
|
|
|
|
While variable substitution is done on all control fields, some of those
|
|
fields are used and needed during the build when the substitution did not
|
|
yet occur.
|
|
That's why you can't use variables in the B<Package>,
|
|
B<Source> and B<Architecture> fields.
|
|
|
|
Variable substitution happens on the content of the fields after they have
|
|
been parsed, thus if you want a variable to expand over multiple lines you
|
|
do not have to include a space after the newline.
|
|
This is done implicitly when the field is output.
|
|
For example, if the variable
|
|
B<${Description}> is set to "foo is bar.${Newline}foo is
|
|
great." and if you have the following field:
|
|
|
|
Description: foo application
|
|
${Description}
|
|
.
|
|
More text.
|
|
|
|
It will result in:
|
|
|
|
Description: foo application
|
|
foo is bar.
|
|
foo is great.
|
|
.
|
|
More text.
|
|
|
|
=head2 Built-in Variable
|
|
|
|
Additionally, the following standard variables are always available:
|
|
|
|
=over
|
|
|
|
=item B<Arch>
|
|
|
|
The current host architecture (i.e. the architecture the package is being
|
|
built for, the equivalent of B<DEB_HOST_ARCH>).
|
|
|
|
=item B<vendor:Name>
|
|
|
|
The current vendor name (since dpkg 1.20.0).
|
|
This value comes from the B<Vendor> field for the current vendor's origin
|
|
file, as L<dpkg-vendor(1)> would retrieve it.
|
|
|
|
=item B<vendor:Id>
|
|
|
|
The current vendor ID (since dpkg 1.20.0).
|
|
This is just the lowercase variant of B<vendor:Name>.
|
|
|
|
=item B<source:Version>
|
|
|
|
The source package version (since dpkg 1.13.19).
|
|
|
|
=item B<source:Upstream-Version>
|
|
|
|
The upstream source package version, including the Debian version epoch if
|
|
any (since dpkg 1.13.19).
|
|
|
|
=item B<binary:Version>
|
|
|
|
The binary package version (which may differ from B<source:Version> in
|
|
a binNMU for example; since dpkg 1.13.19).
|
|
|
|
=item B<Source-Version>
|
|
|
|
The source package version (from the changelog file).
|
|
This variable is now
|
|
B<obsolete> and emits an error when used as its meaning is different from
|
|
its function, please use the B<source:Version> or B<binary:Version> as
|
|
appropriate.
|
|
|
|
=item B<source:Synopsis>
|
|
|
|
The source package synopsis, extracted from the source stanza
|
|
B<Description> field, if it exists (since dpkg 1.19.0).
|
|
|
|
=item B<source:Extended-Description>
|
|
|
|
The source package extended description, extracted from the source stanza
|
|
B<Description> field, if it exists (since dpkg 1.19.0).
|
|
|
|
=item B<Installed-Size>
|
|
|
|
The approximate total size of the package's installed files.
|
|
This value is
|
|
copied into the corresponding control file field; setting it will modify
|
|
the value of that field.
|
|
If this variable is not set
|
|
B<dpkg-gencontrol>
|
|
will compute the default value by accumulating the size of each regular
|
|
file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for
|
|
any other filesystem object type.
|
|
With hardlinks only being counted once as a regular file.
|
|
|
|
B<Note>: Take into account that this can only ever be an approximation,
|
|
as the actual size used on the installed system will depend greatly on the
|
|
filesystem used and its parameters, which might end up using either more
|
|
or less space than the specified in this field.
|
|
|
|
=item B<Extra-Size>
|
|
|
|
Additional disk space used when the package is installed.
|
|
If this
|
|
variable is set its value is added to that of the
|
|
B<Installed-Size>
|
|
variable (whether set explicitly or using the default value) before it
|
|
is copied into the
|
|
B<Installed-Size>
|
|
control file field.
|
|
|
|
=item B<S:>I<field-name>
|
|
|
|
The value of the source stanza field
|
|
I<field-name>
|
|
(which must be given in the canonical capitalization; since dpkg 1.18.11).
|
|
Setting these variables has no effect other than on places where they
|
|
are expanded explicitly.
|
|
These variables are only available when generating binary control files.
|
|
|
|
=item B<F:>I<field-name>
|
|
|
|
The value of the output field
|
|
I<field-name>
|
|
(which must be given in the canonical capitalization).
|
|
Setting these
|
|
variables has no effect other than on places where they are expanded
|
|
explicitly.
|
|
|
|
=item B<Format>
|
|
|
|
The
|
|
B<.changes>
|
|
file format version generated by this version of the source packaging
|
|
scripts.
|
|
If you set this variable the contents of the
|
|
B<Format>
|
|
field in the
|
|
B<.changes>
|
|
file will change too.
|
|
|
|
=item B<Newline>, B<Space>, B<Tab>
|
|
|
|
These variables each hold the corresponding character.
|
|
|
|
=item B<shlibs:>I<dependencyfield>
|
|
|
|
Variable settings with names of this form are generated by
|
|
B<dpkg-shlibdeps>.
|
|
|
|
=item B<dpkg:Upstream-Version>
|
|
|
|
The upstream version of dpkg (since dpkg 1.13.19).
|
|
|
|
=item B<dpkg:Version>
|
|
|
|
The full version of dpkg (since dpkg 1.13.19).
|
|
|
|
=back
|
|
|
|
=head1 FILES
|
|
|
|
=over
|
|
|
|
=item B<debian/substvars>
|
|
|
|
List of substitution variables and values.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<dpkg(1)>,
|
|
L<dpkg-vendor(1)>,
|
|
L<dpkg-genchanges(1)>,
|
|
L<dpkg-gencontrol(1)>,
|
|
L<dpkg-shlibdeps(1)>,
|
|
L<dpkg-source(1)>.
|