chiark - git - mdw - dpkg/blob - man/deb-substvars.man

   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).