Part 6. Managing Configuration Files

By now, you have probably worked enough with your project to understand that it is controlled by a configuration file, and that you can edit that file to modify the source files, targets, and options for your project. You may also have noticed that the configuration file, or .icc file, is coded in a structured language similar to C or C++.

In this section, you will add two user variables to the configuration, one for a working version of your target and one for a production version. You will apply options to each version. You will then create a third user variable and add an if-block to your code, so that, depending on that third variable's setting, either the working version or the production version will be generated when you build.

This section should take you approximately 45 minutes to complete. In working through it, you will learn to perform the following IDE tasks:

Prerequisites If You Are Starting Here

You should have the following source files in a directory on your system. Click the link to see the file's contents. Any changes you may need to make for your environment are indicated in the files.

Review of Configuration Pages and Views

There are two principal purposes for your project configuration:

Select the Configuration section, then the Options page. For future reference, you can use the Options page to set options for specific target or source objects in your project. To do this you would first select a source or target object in the Source and Targets view on the left, then apply options specifically to the selected source or target by changing options in the Change Options view to the right. See Setting Build Options in the Tour of the IDE.

Next, select the Source and Groups page. The Source and Groups view shows that your source files are grouped into two source directives, the second group containing only macros.hpp, the first group containing all other source files mentioned in the configuration file. macros.hpp is in its own group because earlier in this tutorial, you applied the global macros option to that file only. If you select the source directive object for macros.hpp, the current line of the source view underneath changes to show the source specifier for this file, and you can see the global macros option enclosing the source directive.

If you wanted to add more source files whose macros should be treated as having global scope, you could select this source directive in the Source and Groups view, enter the new file names in the Source entry field of the Change Source and Groups view to the right, and click Add, then Apply. Note that this action does not create the source file for you; if you want to create a source file and add it to an existing project, the best way is to use the Open File dialog, and check the box to add the file to a source directive. A subsequent dialog asks you which source directive to add the new file to, and a source view then lets you create the contents of the new file.

You can apply actions to most objects in the configuration views by clicking mouse button 2 over the object. A pop-up menu appears, showing which actions you can perform on the object. You can select multiple objects and click mouse button 2 over any one of them. A pop-up menu will display any actions that apply to all the objects selected. For example, you can select several source files in a Source and Targets view, click mouse button 2, and select Remove from the pop-up menu to remove all the files from your configuration, or you can change the paths of all selected files to relative paths (relative to the project working directory), or to full paths.

The next page is the Targets page, where you will see a list of the targets for your project in the Targets view, with a list of the associated source directives for each target in the view beneath. If you select the Target object in the Targets view on this page, you can modify the target path in the Change Targets view to the right by editing the entry and clicking Apply.

The Project Options page is useful for setting options that apply to the entire project. When you first set options from this page, the IDE creates a named option called ProjectOptions that sets the options you choose, and encloses the entire configuration (source directives, target directives, other options) within its braces. By enclosing the rest of the configuration within the ProjectOptions group, the IDE enables future options applied to this group to apply to the entire project. Note, however, that if you edit your configuration file later, and add configuration information outside the ProjectOptions group, options you set from the Project Options page will not affect these additions.

The Options Groups page shows groups of options for your project. By default, options that all apply to the same part of your configuration (for example, a source directive) are gathered into an unnamed group. This page is a good starting point if you are trying to locate an option you know you have set, when you can't remember what files the option applies to in your configuration. Option check boxes and radio buttons appear shaded or hashed if the default value is currently being used. Descriptions are shown in green for those options you have explicitly changed.

In the Options Groups view at the left you should see two unnamed groups, one for global macros and the other for all other options. You can select any of these groups of options and modify the options settings in the Change Options Groups view to the right. The options you add are added to the group, while the options whose default values you restore are removed from the group. From the Change Options Groups view you can not only change option settings, you can also give an option directive a name or remove a name.

You will use the Options Groups page to make the first changes to your configuration. The two remaining pages are Advanced and Source.

The Source page shows an editable Source view of the configuration file.

The Advanced page shows two views of the configuration, a Details view and an Interpreted view. Both views are hierarchically organized, collapsible views of the contents of your configuration. The Details view includes any changes you have made to the configuration since the last build, other than direct editing changes. (For example, changes you made by adding source files through a dialog or pop-up menu are displayed in this view). The Interpreted view reflects the configuration file as currently interpreted by VisualAge C++. Where a variable is used in an expression, it displays the current value of the variable rather than its name; it displays in grey text those sections of the configuration that were not interpreted (for example, those contained in if blocks whose conditions evaluated to false). The Interpreted view does not reflect changes you make in the Details view until you do one of the following:

The Advanced page is very useful for ensuring that the changes you make have the intended effect while modifying your configuration.

Add Options Groups to the Configuration

You will start changing the configuration by creating two simple, named options groups, one for the working version of the program, one for the production version. The working version uses the shared versions of the run-time libraries; the production version is statically linked to the run-time libraries, and is also optimized. Follow these steps to create these two groups:

  1. In the Configuration section, select the Options Groups page.
  2. In the Options Groups view, move the mouse over a blank area of the view and raise a pop-up menu (click mouse button 2). Select Add Option...
  3. In the Add Option dialog that opens, enter the name WorkingVersion in the Group entry field at the top of the dialog, and click Apply. If you wanted to you could set the applicable options within this dialog; however, because the dialog does not support Live Find, it is easier to save the options group as is, then apply the changes from within the Options Group page.
  4. Repeat steps 1 and 2 for another new option, and name this one ProductionVersion.
  5. Select WorkingVersion in the left view, and in the Change Option Groups view to the right, turn on the option to link with the shared libraries (use Live Find and type shared to locate this option). Click Apply to save this change.
  6. Select ProductionVersion in the left view, and turn off the option to link with the shared libraries. (You may need to click this box twice; it is a three-state checkbox, whose values are on, off, and default. Turn the option off.). As well, turn on optimization by using Live Find to locate "Optim", and pressing Enter or Ctrl+N until the current option selected is "Optimization", with two choices below it, "Yes" and "No". Change the choice to "Yes". Click Apply to save these changes.

    Live Find is case-sensitive by default; if you search "optim" instead of "Optim", the search will not locate the options you are looking. To turn off the case-sensitivity for this view, click the icon to the left of the text entry field and turn off case sensitivity from the menu. You can also set other Live Find options from this menu.

Go to the Advanced page. Notice that these options groups appear with no source or targets within them. You will not add any source or targets to them; instead, you will assign one or the other option to a third variable, depending on whether you are still developing the program or are ready to ship it.

Create a Variable in the Configuration

Configuration files support untyped user variables (variables in which the type is determined by the assignment, not by a type declaration). You can add the definition abc="def" to your configuration file, and abc will be treated as a string containing the characters "def". You can then use comparison operators to compare variables of compatible types, or to compare a variable to a constant.

For this configuration file, you need to define a variable ReadyToShip, with a value of either "true" or "false", and a variable LinkOptions, whose value is determined by the value of ReadyToShip. You need to make these changes in a source view of the configuration.

  1. Select a page of the Configuration section that has a source view, for example the Source page.
  2. In the source view, you can, if you like, delete the empty braces after ProductionVersion and WorkingVersion, although the braces do not affect the syntax. You can highlight and delete a range of lines by moving the cursor, pressing Alt+L on the first and last lines you want to select, then pressing Alt+D.
  3. At the top of the configuration file, insert the following:
    ReadyToShip="false"
  4. Below the ProductionVersion and WorkingVersion options you recently defined, add the following configuration code:
    if (ReadyToShip=="true")
       option LinkOptions=ProductionVersion
    else
       option LinkOptions=WorkingVersion

When you make changes to your configuration, you need to either rebuild your project, or refresh the configuration views, to see how your changes affect the configuration. Rebuilding the project is time-consuming, because when you change your configuration even slightly, the entire codestore may need to be recompiled. This differs from source code changes, where small changes usually result in short rebuild times.

Before you refresh configuration views, you must save your configuration file if you made any changes to it in a source view. Select the source view where you edited the configuration file, and press Ctrl+S to save it.

The IDE lets you view configuration file changes without rebuilding. Select Refresh Configuration Views either from the Project Workbook menu, or from the pop-up menu that appears when you click mouse button 2 over the tab for the Configuration section. Then go to the Advanced page. Notice that, in the Interpreted Configuration view, the statement option LinkOptions = ProductionVersion is grayed out, because the if-block containing this statement did not get evaluated. Also notice that the value of the variable ReadyToShip is shown in the if statement, instead of the variable name.

Add the LinkOptions Option to the Target Statement

Now you will make use of the LinkOptions variable you defined above in determining what link options are applied to the target executable.

  1. If you are not already on the Advanced page of the Configuration section, switch to that page.
  2. In the Details view, position the mouse pointer over the shared library option that currently precedes the target object.
  3. Click mouse button 2, and select Remove from the pop-up menu. This removes the shared library option from the target specifier. You will be prompted to confirm this action. Click OK.
  4. Select the Options page.
  5. Select the target object in the Source and Targets view.
  6. In the Change Options view, look for the Option Variables entry field near the bottom. In this field, enter LinkOptions, the variable you previously defined. Click Add below this field, then on Apply at the bottom of the view.

Rebuild the project. Now, whenever you want to switch between a shared-library development version, and a nonshared-library production version, you can go to a source view of your configuration, change the value of ReadyToShip from "false" to "true" or from "true" to "false", and rebuild.

This part of the tutorial described ways to customize your configuration file. If you use the SmartGuides to build your project, you will probably not need to do this kind of customization for simple projects such as the one in this tutorial. Simply changing the appropriate link option in a Change Options view of the target object would accomplish the same result. However, for larger projects, the ability to customize your configuration is important. See the Configuration Files section in the Concepts information for further details.

You can proceed to the following parts of the tutorial: