Table of Contents
This chapter explains how to manage configuration options in WinGDB.
WinGDB offers many settings allowing it to adjust to different platforms and debugging scenarios. These settings can be remembered in several ways. Sometimes it is needed to store settings (or some of them) only per-user on single machine. Other times it is desirable to permanently remember some settings in a project file, so that they can be stored in version control system. Yet another possibility is exporting them to XML file. In order to satisfy these varied requirements, WinGDB offers a setting management system which is described below.
Most functions related to settings management are located in the Manage properties submenu available in the WinGDB context menu on a project or solution.
All of the options available in WinGDB for a project or solution can exist on two levels: persistent level and user level. These are two separate blocks of option values. Every option can have an explicitly set value on either level (or both) or stay with default value.
When an option has a default value on the user level, that means it inherits the value from the persistent level. In other words, the persistent level provides default values for the user level. If some option has a default value on persistent level, the value is equal to some reasonable predefined value, or in some cases inherited from global Preferences.
The persistent level options are stored in project and solution files (vcproj, vcxproj and sln) You can add them to your version control system and this way remember them permanently or share with other developers. Only options which have non-default values are physically stored. Hence, if you want to store some option this way, just set its value in the Properties dialog. The option value will be displayed bold to indicate that. It can even be equal to the default value, it suffices that you explicitly provide it. You can also reset every option to default value by clicking the button and choosing Default. This way you can control which options have to be stored in your project files and which should not.
You can edit persistent options by choosing Persistent properties from the Manage properties menu or Solution Explorer toolbar menu.
The user level options are stored in standard suo files maintained by Visual Studio. The rules are the same as for the persistent level. If you leave any option as default, it will not be written to the suo file, but inherit the value from corresponding presistent option (which also can be default). If you set an option here, it will override the inherited value. This can be suitable for machine and user specific options, which are not desirable to persist them in source control repositories. Any option can be overriden.
You can edit user options by choosing Properties from the WinGDB context menu. Also the Project configuration wizard accessible from that menu currently alters only user properties.
There is also a different option layering, independent from the persistent/user one. Any option can be set on the solution level or the project level. Solution options becomes defaults for project options in similar way as described above. The exact path of inheritance is as follows:
The arrows go from base to overriding option block. Some settings are solution-wide and available only at the solution level.
In addition to being layered as persistent/user and solution/project, all options are set per configuration, which is basically standard Visual Studio Configuration/Platform distinction, extended by WinGDB with third coordinate called System. For more information, consult this section of the manual.
Most functions regarding options work on either on currently set Configuration, Platform and System, or on full list of all defined Configurations, Platforms and Systems. It depends on where on these approaches does make sense.
There is also way to remember options (from either level) in XML file. Open the Manage properties submenu and select Export or Export persistent. WinGDB will ask you for the destination file. Selecting Import or Import persistent allows you to load previously saved settings file.
These actions are available both for projects and the solution. The solution variant saves both the solution-level settings, and settings for all contained projects. The project variant saves only settings for selected project.
In both cases, projects are identified by names. There is a special case when you export settings for some project, and then import the file for different project. WinGDB will ask you whether it should overwrite existing properties of the destination project. This way you can copy settings between projects or levels, or use the file as a template.
Importing and exporting concerns settings for all defined configurations, platforms and systems.
There are also two other options, allowing to set all settings of currently selected project to default values. This operation may concern either current configuration/platform/system only (Set current configuration to default) or all defined configurations/plaforms/systems (Set all to default). Setting to default effectively removes WinGDB settings from the project, reverting it to regular Visual Studio project.
Many of the settings involve editing lists of values, for example environment variables, additional include directories, etc. These values are usually separated by a space or semucolon character. For easier editing such lists, WinGDB offers Edit... option accessible from the menu displayed when the button next to approppriate field is clicked:
Clicking this option opens the value editor window, which displays each value in separate line.
The editor has also three buttons, allowing you to move current line (in which the cursor is positioned) up or down relatively to other lines. The third button opens the file browser dialog, allowing to choose some path in the file system and insert it into the editor. This button appears only when editing certain settings and is a counterpart of the Browse... option available for single-value path options.
In addition to Visual Studio macros, you can use your own variables. They are used in similar way as macro variables. The syntax is $(WGC.name) where name is the variable name.
Custom variables can be defined on various levels, being seamlessly integrated into the user/persistent option management mechanism. There are five possible levels. Levels listed first are inheritance base for levels listed after them. The latter levels override values from previous levels on per-value basis.
Custom variables are defined separately for each Configuration, Platform and System except for the global level variables which are common.
Use $(WGC.name) syntax to refer to the custom variable. You can put such a reference in any WinGDB option of string type (including paths).
Caution: regular Visual Studio project options do not recognize custom variables. Only those settings that are added by WinGDB can expand them.
Caution: custom variables make sense only when you are working with project/solution. The quick mode does not allow usage of custom variables.
The inheritance mechanism is designed in such way, that appropriate final value is determined in the context where the option is actually being used. For example: you can have following defined:
Now, when you build the project, it will log in as email@example.com. The logic behind this is as follows: the project inherits $(WGC.user)@$(WGC.host) login value from the solution. Then, variable expansion is being performed. The user value is inherited from the global level. The host variable has been set directly on the project level, so it is not inherited. The expansion process substitutes variable references into determined values. The result is firstname.lastname@example.org.
You can use VS macro variables (described earlier, e.g. $(Configuration)) inside custom variable definitions. The expansion process is two-stage. First, custom variables are expanded and resulting value is being subject to VS macro expansion.
You can use custom variables in makefiles generated by Lua script. The evaluate function expands custom variables and VS macro variables in the same way as described above.
Table of Contents