summaryrefslogtreecommitdiffstats
path: root/man/deb-substvars.pod
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/deb-substvars.pod251
1 files changed, 251 insertions, 0 deletions
diff --git a/man/deb-substvars.pod b/man/deb-substvars.pod
new file mode 100644
index 0000000..517675f
--- /dev/null
+++ b/man/deb-substvars.pod
@@ -0,0 +1,251 @@
+# 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> or
+I<name>B<?=>I<value>.
+The B<=> operator assigns a normal substitution variable, while the B<?=>
+operator (since dpkg 1.21.8) assigns an optional substitution variable
+which will emit no warnings even 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 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 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<fieldname>
+
+The value of the output field
+I<fieldname>
+(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
+
+B<dpkg>(1),
+B<dpkg-vendor>(1),
+B<dpkg-genchanges>(1),
+B<dpkg-gencontrol>(1),
+B<dpkg-shlibdeps>(1),
+B<dpkg-source>(1).