diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/deb-substvars.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/deb-substvars.pod | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/man/deb-substvars.pod b/man/deb-substvars.pod new file mode 100644 index 0000000..8048f10 --- /dev/null +++ b/man/deb-substvars.pod @@ -0,0 +1,241 @@ +# 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> + +=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. + +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. + +After all the substitutions have been done each occurrence of the +string +B<${}> +(which is not a legal substitution) is replaced with a +B<$> +sign. + +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. + +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> +option). This file consists of lines of the form +I<name>B<=>I<value>. +Trailing whitespace on each line, blank lines, and +lines starting with a +B<#> +symbol (comments) are ignored. + +Additionally, the following standard variables are 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 B<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<fieldname> + +The value of the source stanza field +I<fieldname> +(which must be given in the canonical capitalisation; 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<fieldname> + +The value of the output field +I<fieldname> +(which must be given in the canonical capitalisation). 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 + +If a variable is referred to but not defined it generates a warning +and an empty value is assumed. + +=head1 FILES + +=over + +=item B<debian/substvars> + +List of substitution variables and values. + +=back + +=head1 SEE ALSO + +B<dpkg>(1), +B<dpkg-vendor>(1), +B<dpkg-genchanges>(1), +B<dpkg-gencontrol>(1), +B<dpkg-shlibdeps>(1), +B<dpkg-source>(1). |