Next: Extending Projects, Previous: Supported Languages, Up: Project Handling

### 7.3 Scenarios and Configuration Variables

The behavior of projects can be further tailored by the use of scenarios.

All the attributes of a project, except its list of imported projects, can be chosen based on the value of external variables, whose value is generally coming from the host computer environment, or directly set in GPS. The interface to manipulate these scenarios is the scenario view, which can be displayed by selecting the menu `Tools->Views->Scenario`. It can be convenient to drag this window with your mouse, and drop it above the project view, so that you can see both at the same time.

This area allows you to select new values for the scenario variables defined in your project, and thus change dynamically the view GPS has of your project and your source files.

This facility can for instance be used to compile all the sources either in debug mode (so that the executables can be run in the debugger), or in optimized mode (to reduce the space and increase the speed when delivering the software). In this configuration scenario, all the attributes (source directories, tools, ...) remain the same, except for the compilation switches. It would be more difficult to maintain a completely separate hierarchy of project, and it is much more efficient to create a new configuration variable and edit the switches for the appropriate scenario (The Project Properties Editor).

There is one limitation in what GPS can do with scenario variables: although gnatmake and gprbuild have no problem dealing with scenario variables whose default value is not a static string (for instance a concatenation, or the value of another scenario variable), GPS will not be able to edit such a project graphically. Such projects will load fine in GPS though.

#### 7.3.1 Creating new configuration variables

Creating a new scenario variable is done through the contextual menu (right-click) in the Project View or the Scenario View itself. Select the menu `Project->Add Configuration Variable`. This opens the following dialog:

There are two main areas in this dialog: in the top line, you specify the name of the variable. This name is used for two purposes:

- It is displayed in the scenario view
- This is the name of the environment variable from which the initial value is read. When GPS is started, all configuration variables are initialized from the host computer environment, although you can of course change its value later on inside GPS. Note that selecting a new value for the scenario variable does not change the actual value of the environment variable, which is only used to get the default initial value of the scenario variable.

  When you spawn external tools like gnatmake for instance, you can also specify the value they will use for the scenario variable by using a command line switch, typically `-X`.

If you click on the arrow on the right of this name area, GPS will display the list of all the environment variables that are currently defined. However, you don't need to pick the name of an existing variable, neither must the variable exist when GPS is started.

The second part of this dialog is the list of authorized value for this variable. Any other value will generate an error reported by GPS, and the project won't be loaded as a result.

One of these values is the default value (the one whose button in the Default column is selected). This means that if the environment variable doesn't exist when GPS is started, GPS will behave as if it did exist with this default value.

The list of possible values can be edited by right-clicking on the name of the variable, and selecting one of `Edit properties` or `Delete variable`.

#### 7.3.2 Editing existing configuration variables

If at least one configuration variable is defined in your project, the scenario view will contain something similar to:

This screen shot shows two configuration variables, named `Build` and `OS`, with their current value (resp. `Debug` and `Unix`).

You can easily change the current value of any of these variables by clicking on the arrow on the right of the value. This will display a pop-up window with the list of possible values, from which you select the one you wish to use.

As soon as a new value is selected, GPS will recompute the project view (in case source directories, object directories or list of source files have changed). A number of things will also be updated (like the list of executables in the `Compile`, `Run` and `Debug` menus).

Currently, GPS will not recompute the contents of the various browsers (call graph, dependencies, ...) for this updated project. This would be too expensive to do every time the value changes, and therefore you need to explicitly request an update.

You can change the list of possible values for a configuration variable at any time by clicking on the button to the far left of the variable's name. This will pop up the same dialog that is used to create new variables. This dialog also allows you to change the name of the scenario variable. This name is the same as the environment variable that is used to set the initial value of the scenario variable.

Removing a variable is done by clicking on the button immediately to the left of the variable's name. GPS will then display a confirmation dialog.

If you confirm that you want to delete the variable, GPS will simply remove the variable, and from now on act as if the variable always had the value it had when it was deleted.