Many software packages have configuration files that must be edited before the software can be used. To the developer of a software package writing the configuration files may be trivial, but this is often not the case for the end user. For this reason, the ReST Installer may be used to edit configuration files for the software package. The package must include a stub configuration file with a series of tokens to substitute. Each token appears with a % character on either side of the token, such as %token%. With a stub file created the packager must define the substitutions for this file in the Packager.

The configuration files are a special catigory of package files as stated above. The configuration (config) file tokens are substituted during transfer after all the package files are tranferred and the preparation commands are completed. To add a config file to the package, browse to the files containing the tokens or type in the location and choose import. As the files are imported, they are scanned for any tokens contained and the number of tokens is displayed in the tokens column. Double clicking on a row or right clicking on it and selecting view will display the file in the viewer. If a config file needs deletion, right click on the file and select remove. The complete file path can be viewed as a tooltip by hovering the mouse cursor over the row as seen in figure 2.

Figure 1.2. Select Configuration Files

Selecting configuration files is easily done using the packager.

Once all the config files have been imported into the Packager the Setup Config Files panel display's the config files tokens needing to be setup. The configfiletag has three attributes: packagefile (the location of the stub file in the package), remotefile (where the resulting configuration file should be placed on the remote machine), and description (a simple description for the user). Addtional information about the configfileand subtags, including additional attributes to each, can be found in the reference section at the end of this document. Figure 3 shows the "config" config files with four tokens titled "boolean", "string", "choice" and "text". When the Setup Config Files panel initially loads, each config file is listed with a collapasable section containing the tokens. The first config file initially is expanded as show for the "config" configuration file in Figure 3. Each token also has a collapsable section under it, as show in Figure 4, with the various types of substitutions that can performed. It is important to note the names of the tokens are very important because they are what is displayed to the user when prompting for input.

Figure 1.3. Configuring Substitutions

Setting-up the configuration files substitutions

Once all the configuration files have been entered the Setup Config Files panel displays all the configuration (config) files with an associated listing of all the config files tokens. Each config file token also has a hidable section allowing for selecting the type of substitution and setting up the token. Every token requires several common inputs, Type, Descrption and Default. The subtitution type determines what the installer displays for input. Boolean displays a checkbox with the associated token name. String displays a single line text input box. Choice displays a dropdown box, similar to the box for Type, that can be made editable by the packager by selecting the oppropriate checkbox. The choice values are input in a comma delimited list and may contain spaces. The final substitution type is text. The text area allows for substitutions to be made containing special characters such as tabs and newlines. As with all components, any field with a yellow background signifies required field for the specific substitution type.

Figure 1.4. Configuring Substitutions

Types of configuration files substitutions

In the previous two figures, four substitutions are made, but ReST will handle as many substitutions as are needed. Each of the four substitions represents a type of substitution supported by ReST , string(no more than one line of text), text(multiple lines of text), choice(a defined set of choices, much like available for command options) and boolean (a checkbox defining if a predefined substitution should take place). Each substitution type is useful for different types of substitutions. For example, boolean substitutions are useful when a single line needs to be commented or uncommented. This could be done by the following example

#Uncomment the next line to enable 3D mode %Enable 3D
      Mode%enable-opengl

The token is "Enable 3D Mode" and the most useful stubstituion type would be boolean. With the boolean type selected, two new fields are displayed, true value and false value. The user is displayed a checkbox when setting up the config file. If Default is set to "true" then the default substitution made is with the true value, otherwise, the false value is used for the substitution. So, if the true value is set to "" and the false value is "#", the user can change the value easily in a familiar way but clicking on a check box followed by "Enable 3D Mode".

Figure 1.5. Configuring Substitutions

Types of configuration files substitutions

The boolean substitution has the most complex substitution usage avaiable in ReST. The other substitutions have less options avaiable and are therefore less complex in their usage. The types of substitutions that are not boolean all have a default value. If no user customized value is provided then the default it substituted when the substitution takes place for all types except boolean.