Project variables

Tarma QuickInstall projects contain many pieces of information that are either not known until installation time (for example, the location of the Program Files or Windows folders on the customer's computer), or that are known, but are used in several places and must be kept consistent throughout the project.

To solve both problems at once, Tarma QuickInstall uses project variables. Project variables have the form <Name> and act as placeholders for information stored elsewhere. When the Tarma QuickInstall Setup program runs, it substitutes the actual information for each placeholder. This allows you to change the information in one place and be confident that those changes are automatically propagated to all other places that require the same information.

Tarma QuickInstall contains nearly 80 predefined project variables, which are listed in the Predefined variables topic.

Referencing project variables

To refer to a project variable elsewhere in the project, enter the name of the variable enclosed by < and > characters. For example, to refer to the application title you would enter <AppTitle>. Variable names are not case sensitive; <apptitle> would refer to the same variable.

Note - If you need to insert a stand-alone < character for some reason, be sure to place a space after the < to avoid confusion with project variable references. Stand-alone > characters are only allowed outside variable references, but require no special precaution otherwise.

As a convenience, most of the project pages contain variable popup buttons

next to their edit fields. When you click this kind of button, a popup menu appears that lists variables appropriate for the context. If the variable you are looking for isn't listed, use the Browse for Variable... option that appears at the bottom of each variable menu; this gives you access to the entire list of variables, including any custom variables that you may have defined.

Recursive variables

You may define project variables in terms of other variables. For example, the default value for the <AppFolder> variable is <ProgramFiles>\<Company>\<AppTitle>. When Tarma QuickInstall resolves a variable, it will correctly handle this kind of recursion, but only up to a level (currently up to 15 levels deep) to detect circular variable definitions that would lead to infinite recursion.

(As a simple example, if you were to define <AppTitle> as <ProgGroup>, and <ProgGroup> as <AppTitle>, neither variable could be properly resolved.)

Therefore, if you do define variables in terms of other variables, you should make sure that they ultimately lead to predefined variables that contain only literal text, are marked (runtime) in the Variables list, or obtain their value from system information (see below).

System information variables

Many of the predefined variables, and also any custom variables that you may define, refer to system information in the registry, environment, or INI files on the customer's computer. At installation time, Setup resolves these variables by substituting the actual values from the customer's computer.

Refers to a normal variable lookup. At runtime, Setup will look up the value of variable name and substitute its value. This substitution is recursive; if necessary, the value is further resolved if it in turn contains variable references.

Example - The expression <AppFolder> retrieves the installation folder path.

Refers to a registry value. At runtime, Setup resolves regpath, which must ultimately be in the form HKEY_xxx\key\...\key\value, then retrieves the corresponding value from the registry. Some hints and tips:

REG_EXPAND_SZ - Retrieved with expansion. All environment variable references within the value are expanded before the value is used in the variable.

REG_MULTI_SZ - Only the first 0-terminated string is used; the others, if any, are ignored.

Refers to an environment variable (note that this requires only a single leading '%' character, not a leading and a trailing character as is customary in command processors). At runtime, Setup retrieves the value of the environment variable varname.

Example - The expression <%Path> obtains the value of the PATH environment variable.

Refers to an INI file value. At runtime, Setup resolves the inipath?section?key expressions, which must ultimately resolve to, respectively, the path to the INI file, the name of a section within that file, and the name of a key in that section. As in other places, you may use variables in any of the subexpressions.

Example - You could use <#<WinIni>?<Company>?<AppTitle>> to retrieve some company- and application-specific information from the Windows win.ini file. Note that the expression in this example ends with two '>' characters because it uses nested variable references.

Resolves to (the expanded version of) text. This is not particularly useful in itself, as you could achieve the same result with less typing by simply using text without any of the '<' and '>' characters. However, it is useful in conjunction with alternative values; see below. Again, text may contain references to other variables; they will be expanded as expected.

Example - The expression <!AppFolder> would result in the text "AppFolder" instead of looking up the <AppFolder> variable; <!<AppFolder>> would do the look up and then pass on the result unchanged.

Alternative values

Occasionally, it is useful to have alternative values available as a fallback mechanism. Tarma QuickInstall uses this extensively in its predefined variables to cater for differences between the various Windows platforms.

With this syntax, ref1 to refn are variable references as defined above, but without the enclosing '<' and '>' characters (the outermost '<' and '>'. delineate the expression). In particular, you can refer to variables by name without further ado; viewed in this way, <name> is just an expression with no alternative values.

At runtime, Setup evaluates the references from left to right and stops as soon as one of them evaluates to a non-empty value. This is then used as the value for the entire expression.

This expression resolves to the value of the <Common_Desktop> variable, which is defined elsewhere and resolved before use. If this value happens to be empty (a common occurrence on Windows 9x), the value of the <User_Desktop> is tried next in the same manner.

The first part of this expression consists of a runtime reference to a registry value (specified through further project variables); if that value happens to be empty or missing, the alternative value is based on the user's Profile folder path.

Note the use of the '!' to force the use of the <User_Profile>\Cookies expression as-is; without the '!', Setup would try to use the value of <User_Profile>\Cookies as a variable name, because it is still operating inside the outermost '<' and '>'. context.

Variables syntax

The following is an annotated syntax specification for project variables. It uses a mixture of regular expression and EBNF notations, which should be familiar to most programmers. The specification is not completely rigorous; in places it relies on plain English for semantical or further syntactical restrictions.

This specifies the concept of "text" as being any sequence of characters and symbols, with the special provision that the text may not contain '<' characters (because they are used to start symbols).

This describes a symbol as consisting of an opening '<' character, followed by a symbol reference, optionally followed by further symbol references that act as alternative values (see above), and ending with a '>' terminator.

This describes a symbol reference as either a symbol name, or a '%' character followed by the name of an environment variable, or a '@' character followed by a registry path, or a '#' character followed by an INI file path, section, and key name, or a '!' character followed by some restricted text.

This specifies restricted text as any sequence of characters and symbols, with the provision that the text may not contain '<' (because that starts a symbol), '>' (because that closes the parent symbol), or '=' (because that starts an alternative symbol reference).

This defines a symbol name as starting with an underscore or a letter, followed by zero or more further underscores, letters, and digits. Note that Tarma QuickInstall currently accepts a much wider range of characters in symbol names; however, for future compatibility, you should restrict symbol names to this specification.

Note - Tarma QuickInstall currently accepts restr_text for symname. Among other things, this allows you to use double (and triple, quadruple, ...) indirect symbol references, for example "<<Name>>", which would look up the value of the "Name" symbol and use that value (possibly after expansion) as the name of the symbol to look up next. This final lookup would then serve as the value for the original reference.

This defines the name of an environment variable as consisting of any restricted text sequence. In practice, Windows may apply further restrictions, so you should only use environment variable names that you know are valid for the Windows versions that you target. Again, symbol references may be used to specify an environment variable name.

This defines a registry path with a top-level key/hive name, a registry key path, and an optional registry value name. (In absence of the value name, the unnamed default value is used.) Note that you may use restr_text for the registry path as long as it resolves to the more detailed syntax variant.

This defines a registry name as any sequence of restricted text and symbols. Note that it excludes some characters ('<', '>', and '=') that are normally allowed in registry paths; there is currently no escape mechanism to prevent this.

This defines a HKEY_xxx registry name, which must ultimately resolve to one of the standard HKEY_xxx registry key names (HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, and HKEY_USERS are currently supported).

This defines a registry key name, which must ultimately resolve to a name that is an existing Windows registry key name.

This defines a registry value name, which must ultimately resolve to a name that is an existing Windows registry value name under the given registry key. Note that in regpath the entire regval portion is optional; omitting it implicitly specifies the unnamed default value for the corresponding registry key.

This defines an INI file path as any file path; it must ultimately resolve to the name of a text file in Windows INI format. Note that you may use any restricted text sequence (including symbol references) as long as it ultimately resolves to the filepath syntax.

This specifies the syntax of a file path, either as drive followed by a path, or as a UNC path. Note that symbol references are allowed for the initial portion; if used, they should ultimately resolve to a letter followed by a colon or a UNC server specification. For example, <WinDrive> is a predefined variable that would be suitable.

This defines the syntax of a file name. Note that it excludes one character ('=') that is normally allowed in a file name; there is currently no escape mechanism to prevent this.

This defines the name of a section in an INI file. In practice, Windows may restrict the allowable names even further, so you should make sure that section ultimately resolves to a valid INI file section name.

This defines the name of a key within an INI file section. In practice, Windows may restrict the allowable names even further, so you should make sure that keyname ultimately resolves to a valid INI file section key name.

Documentation Home | Using Tarma QuickInstall | Knowledge Base
Tarma QuickInstall User's Manual - Topic last modified on 3/04/08 18:19
Copyright © 1990-2008 Tarma Software Research. All rights reserved.