man/deb-substvars.5

   1 .\" Authors: Ian Jackson
   2 .TH deb\-substvars 5 "2009-07-15" "Debian Project" "dpkg utilities"
   3 .SH NAME
   4 deb\-substvars \- Debian source substitution variables
   5 .
   6 .SH SYNOPSIS
   7 substvars
   8 .
   9 .SH DESCRIPTION
  10 Before
  11 .BR dpkg\-source ", " dpkg\-gencontrol " and " dpkg\-genchanges
  12 write their control information (to the source control file
  13 .B .dsc
  14 for
  15 .B dpkg\-source
  16 and to standard output for
  17 .BR dpkg\-gencontrol " and " dpkg\-genchanges )
  18 they perform some variable substitutions on the output file.
  19
  20 A variable substitution has the form
  21 .BI ${ variable-name }\fR.
  22 Variable names consist of alphanumerics, hyphens and colons and start
  23 with an alphanumeric. Variable substitutions are performed repeatedly
  24 until none are left; the full text of the field after the substitution
  25 is rescanned to look for more substitutions.
  26
  27 After all the substitutions have been done each occurrence of the
  28 string
  29 .B ${}
  30 (which is not a legal substitution) is replaced with a
  31 .B $
  32 sign.
  33
  34 While variable substitution is done on all control fields, some of those
  35 fields are used and needed during the build when the substitution did not
  36 yet occur. That's why you can't use variables in the \fBPackage\fP,
  37 \fBSource\fP and \fBArchitecture\fP fields.
  38
  39 Variable substitution happens on the content of the fields after they have
  40 been parsed, thus if you want a variable to expand over multiple lines you
  41 do not have to include a space after the newline. This is done implicitly
  42 when the field is output. For example, if the variable
  43 \fB${Description}\fP is set to "foo is bar.${Newline}foo is
  44 great." and if you have the following field:
  45
  46  Description: foo application
  47   ${Description}
  48   .
  49   More text.
  50
  51 It will result in:
  52
  53  Description: foo application
  54   foo is bar.
  55   foo is great.
  56   .
  57   More text.
  58
  59 Variables can be set using the
  60 .B \-V
  61 common option. They can be also specified in the file
  62 .B debian/substvars
  63 (or whatever other file is specified using the
  64 .B \-T
  65 option). This file consists of lines of the form
  66 .IB name = value\fR.
  67 Trailing whitespace on each line, blank lines, and
  68 lines starting with a
  69 .B #
  70 symbol (comments) are ignored.
  71
  72 Additionally, the following standard variables are available:
  73 .TP
  74 .BI Arch
  75 The current build architecture (from
  76 .BR "dpkg \-\-print\-architecture" ).
  77 .TP
  78 .B source:Version
  79 The source package version.
  80 .TP
  81 .B source:Upstream\-Version
  82 The upstream source package version, including the Debian version epoch if
  83 any.
  84 .TP
  85 .B binary:Version
  86 The binary package version (which may differ from source:Version in a binNMU
  87 for example).
  88 .TP
  89 .B Source\-Version
  90 The source package version (from the changelog file). This variable is now
  91 \fBdeprecated\fP as its meaning is different from its function, please use
  92 the \fBsource:Version\fP or \fBbinary:Version\fP as appropriate.
  93 .TP
  94 .B Installed\-Size
  95 The total size of the package's installed files. This value is copied
  96 into the corresponding control file field; setting it will modify the
  97 value of that field. If this variable isn't set
  98 .B dpkg\-gencontrol
  99 will use
 100 .B du \-k debian/tmp
 101 to find the default value.
 102 .TP
 103 .B Extra\-Size
 104 Additional disk space used when the package is installed. If this
 105 variable is set its value is added to that of the
 106 .B Installed\-Size
 107 variable (whether set explicitly or using the default value) before it
 108 is copied into the
 109 .B Installed\-Size
 110 control file field.
 111 .TP
 112 .BI F: fieldname
 113 The value of the output field
 114 .IR fieldname
 115 (which must be given in the canonical capitalisation). Setting these
 116 variables has no effect other than on places where they are expanded
 117 explicitly.
 118 .TP
 119 .B Format
 120 The
 121 .B .changes
 122 file format version generated by this version of the source packaging
 123 scripts. If you set this variable the contents of the
 124 .B Format
 125 field in the
 126 .B .changes
 127 file will change too.
 128 .TP
 129 .BR Newline ", " Space ", " Tab
 130 These variables each hold the corresponding character.
 131 .TP
 132 .BI shlibs: dependencyfield
 133 Variable settings with names of this form are generated by
 134 .BR dpkg\-shlibdeps .
 135 .TP
 136 .B dpkg:Upstream\-Version
 137 The upstream version of dpkg.
 138 .TP
 139 .B dpkg:Version
 140 The full version of dpkg.
 141 .LP
 142 If a variable is referred to but not defined it generates a warning
 143 and an empty value is assumed.
 144 .
 145 .SH FILES
 146 .TP
 147 .B debian/substvars
 148 List of substitution variables and values.
 149 .
 150 .SH BUGS
 151 The point at which field overriding occurs compared to certain
 152 standard output field settings is rather confused.
 153
 154 .SH SEE ALSO
 155 .BR dpkg (1),
 156 .BR dpkg\-genchanges (1),
 157 .BR dpkg\-gencontrol (1),
 158 .BR dpkg\-shlibdeps (1),
 159 .BR dpkg\-source (1).
 160 .
 161 .SH AUTHOR
 162 Copyright \(co 1995-1996 Ian Jackson
 163 .br
 164 Copyright \(co 2000 Wichert Akkerman
 165 .sp
 166 This is free software; see the GNU General Public Licence version 2 or
 167 later for copying conditions. There is NO WARRANTY.