Working with variables¶
Variables play an important role in Paquet Builder: this topic describes why and how to use them efficiently.
What is a variable?¶
Variables are named storage locations that hold information about the system, information entered by the user, or information derived or calculated from either of these two sources. Variables are special named "containers" for values that change.
We say that values are "assigned to" or "stored in" variables. If you picture a variable as a container that can hold a value, assigning a value to a variable is as "placing" that value into a container. You can change this value at any time by assigning a new value to the variable; the new value simply replaces the old one. This ability to hold changeable information is what makes variables so useful.
Paquet Builder's Variable Characteristics¶
-
Variable names must begin and end with the % percentage sign.
-
Variable names cannot contain the following characters: #, $, ". Only numbers, letters, and underscore ( _ ) characters are allowed. Moreover variable names cannot contain spaces. Example:
%MYVARIABLE%is correct while%MY VARIABLE%isn't. -
They hold Unicode text, not binary data.
-
Variables should not begin with "PB" (reserved for Paquet Builder). For example %PBRES% is not allowed because Paquet Builder uses it internally.
-
Length of Paquet Builder variables is limited to 4096 wide characters.
The advantage of variables is that they let your package adapt to each destination computer. Once information is stored in a variable, it can be used in most custom actions through a process called substitution. Any property for a custom action can get part or all of its value from a variable. Simply specify the desired variable name preceded and followed by a percent (%) character, and it will be replaced by the variable's value: for example, %WIN% refers to the contents of the WIN variable, which is the path to the Windows directory.
Warning
The % symbol is not part of the variable name, but rather a marker that tells the package to replace the variable with its value before executing the command.
You can use variables to build messages to be displayed to the user (instead of resource strings that are constants), to set locations for copying or installing files, and to initialize new variables to the value of one or more other variables. If you are using a variable name as part of an expression, do not surround the variable name with percent (%) signs.
Paquet Builder only supports managing alpha-numeric variables: some actions work with boolean and integer-typed variables. Such boolean variables are considered as string ones that can only take two values: 1 meaning TRUE, 0 meaning FALSE. The boolean variables are especially useful for creating conditional blocks. For example conditional variables and component variables are boolean variables.
Variables support Unicode and string functions used by Paquet Builder packages.
Key custom actions are "Perform operation on a variable" to work with variables and "Begin/End Conditional If/Then" to evaluate values of variables.
Using the Variable Manager¶
The Variable Manager may be accessed by clicking Variables in the ribbon:
Use of the variable manager is not an obligation: you can work with variables without passing through the variable manager, but this is not recommended. The variable manager in fact maintains the list of variables you use for your package and especially with custom actions. It is ideal for remembering the variables you define, especially when they are shared between several custom actions.
Some variables are defined automatically by Paquet Builder; for example, the %WIN% variable contains the path to the Windows directory. These pre-defined variables are called Global variables and their values are automatically set by the package itself at runtime. An extended list is available here.
You can also define your own variables: user-defined variables are called Custom variables and it's up to you to set the value of your custom variables. To initialize a variable (in other words to set its value for the first time), you need to use custom actions like the "Perform operation on a variable". Actually any custom action that outputs a variable may be used: see the list of custom actions.
To add a custom variable to the manager, press the Add button: the following editor is displayed:
-
Variable Name is the name of your variable (a string enclosed in two % signs). Note that variables are unique: if you try to enter the name of an existing variable, Paquet Builder will show a warning.
-
Variable Type: this field lets you enter a type for the variable (if you do not know what to select, just leave Custom). This is especially for remembering the goal of the variable when you use it. Paquet Builder will however use this type when it filters variables for a specific list: for example, in lists containing folders (like the main destination folder field), only variables with the "Path" type will be listed. Paquet Builder includes some types like "Info", "String", "Boolean", "Registry". These types are for information purposes only and not currently used (maybe in future versions).
-
Variable Comment (optional): enter any comment regarding the variable.
You can also remove custom variables from the variable manager by pressing Remove. Note that only custom variables may be removed.
Finally, pressing Reset will cause the variable manager to be reset (as if you start a new project) and all custom variables will be deleted and consequently lost.
About global (pre-defined) variables¶
Paquet Builder automatically provides you with several pre-defined variables for each package project. Pre-defined variables generally contain information about the user's system and its default system and shell folders.