3. Setting Preferences

3.1. GNATbench Preferences

GNATbench allows the user to control a number of behaviors and presentation formats. This section introduces and summarizes the preferences providing those controls.

Most of these preferences are described in detail in the other sections specific to the preference (e.g., automatic indentation is discussed in the Editing section).

In all cases these preferences are initially accessed via the “Window” menu entry and the “Preferences” submenu entry that brings up the preferences dialog box.

invoking preferences

3.2. Builder Targets

GNATbench provides an interface for launching operations like building projects, compiling individual files, performing syntax or semantic checks, and so on. All these operations involve launching an external command and parsing the output for error messages. These operations are called “Targets” and can be configured through this preference page.

Ada Builder Targets Pref Page

3.2.1. The Targets Tree

The Targets Tree contains a list of targets organized by category. In the figure above, we have expanded the categories to show the individual targets currently defined.

To the right of the tree are several buttons:

  • The Add button creates a new target.

  • The Remove button removes the currently selected target. Note that only user-defined targets can be removed, the default targets created by GNATbench cannot be removed.

  • The Clone button creates a new user-defined target which is identical to the currently selected target.

  • The Revert button resets all target settings to their original value.

  • The Properties and the Command buttons invoke the dialogs described below.

At the bottom of the tree are the following buttons:

  • The Restore Defaults button delete all user-added targets, and revert the others.

  • The Apply button saves the modifications and applies them to the platform.

  • The OK button stores the modifications in the current workspace and closes the preference page.

  • The Cancel button closes the preferences page without saving any further changes.

Note that any modifications saved as a result of previously pressing the Apply button will be retained, they are not undone by Cancel.

3.2.2. The Properties Dialog

The Properties dialog allows you to control how the individual command is presented and how it interacts with the user.

Ada Builder Targets Pref properties dialog

On top of the dialog one can select the Target model. The Model determines the graphical options available in the “Command line” frame.

The “Target Options” frame contains a number of options that are available for all Targets.

  • The Launch mode indicates the way the target is launched:

    • Manually: the target is launched when clicking on the corresponding icon in the toolbar, or when activating the corresponding menu item. In the latter case, a dialog is displayed, allowing last-minute modifications of the command line.

    • Manually with dialog: same as Manually, but the dialog is always displayed, even when clicking on the toolbar icon.

    • Manually with no dialog: same as Manually, but the dialog is never displayed, even when activating the menu item.

    • On file save: the Target is launched automatically by GNATbench when a file is saved. The dialog is never displayed.

    • In background: the Target is launched automatically in the background after each modification in the source editor.

  • Icon: the icon to use for representing this target in the menus and in the toolbar.

  • Target type: type of target described. If empty, or set to Normal, represents a simple target. If set to another value, represents multiple subtargets. For example, if set to main, each subtarget corresponds to a Main source as defined in the currently loaded project.

The “Display” frame indicates where the launcher for this target should be visible.

  • in the toolbar: when active, a button is displayed in the main toolbar, allowing to quickly launch a Target.

  • in the main menu: whether to display a menu item corresponding to the Target in the build menu. By default, Targets in the “File” category are listed directly in the Build menu, and Targets in other categories are listed in a submenu corresponding to the name of the category.

  • in contextual menus for projects: whether to display an item in the contextual menu for projects in the Project View

  • in contextual menus for files: whether to display an item in the contextual menus for files, for instance in file items in the Project View or directly on source file editors.

3.2.3. The Command Line Dialog

The “Command Line” dialog contains a graphical interface for some configurable elements of the Target that are specific to the Model of this Target.

Ada Builder Targets Pref command line dialog

The full command line is displayed at the bottom. Note that it may contain Macro Arguments. For instance if the command line contains the string “%PP”, GNATbench will expand this to the full path to the current project.

3.3. Syntax Coloring

The colors for various Ada constructs can be specified via the “General/Appearance/Colors and Fonts” preferences page. In the resulting scrollable tree panel on the right, expand the “Ada” category to see the constructs that can be controlled, as shown in the following figure. To change a color, select the construct category and press the colored button on the upper right of the dialog box. The color of the button indicates the current color selection for that construct category.

Color controls for Ada

3.4. Editors’ Font

The overall text font used by the editors, including the Ada editor, can be selected via the normal Eclipse “Text Font” preference in the “Basic” category (directly below the “Ada” category in the scrollable tree pane on the “Colors and Fonts” page). Note that fonts are not specific to constructs.

To change the font, select “Text Font” and press the Change… button. This will invoke the font selection dialog.

Editors font

3.5. Coding Style

The many style and formatting preferences, including for example automatic indentation and letter casing preferences, are described in the Editing chapter and are controlled by the preferences page shown below. The default values are as shown.

Ada Coding Style Preferences

3.6. Editor

The editor behavior preferences are controlled by the preferences page shown below. All these preferences are described in the Language-Sensitive Editing chapter except for the following:

  • The “remove trailing spaces when saving” preferences controls whether trailing blanks should be removed when Save or “Save As…” action is triggered. Choosing Autodetect will keep trailing blanks only if original file had already trailing blanks.

  • The tooltips preference controls whether tooltips are displayed within the Ada editor. Tooltips are displayed whenever the cursor is “hovered” over an Ada entity.

  • The spelling preference controls whether the text within string literals is checked for correctness.

  • The “Display warnings for foreign Ada source files” preference controls whether a dialog is displayed when invoking the editor on an Ada source file that is not part of any GNATbench project. See Foreign Ada Source Files for details.

Ada editor prefs

3.7. General Preferences

General purpose preferences for Ada are controlled by the dialog page in the following figure. The corresponding preferences dialog page is selected via the “General” page under the “Ada” category. The details of each preference are provided after the figure.

Ada GNATbench General Preferences

3.7.1. Multi-language Builder

This preference controls the builder to be invoked when building a project containing sources written in languages other than, or in addition to, Ada.

By default, gprbuild will be used. Alternatively, its prototype gprmake can be selected to help transition to gprbuild. General use of gprmake is not recommended.

To select gnatmake you can use the gnatmake setting, even for a project containing non-Ada sources, but note that gnatmake will only process Ada source files, ignoring all others. Use in a multi-lingual project is therefore not recommended.

Finally, to always use gprbuild, even when Ada is the only language involved, you can select the gprbuild_always setting.

3.7.2. Fast Project Loading

If enabled, the %eL token is replaced by -eL “Follow symbolic links when processing project files” when expanding builder commands. Symbolic links should not be used in the project. More precisely, you can only have symbolic links that point to files outside of the project, but not to files in the project.

3.7.3. Removal Policy When Fixing Code

This preference controls the way Quick Fix works when parts of the source code must be removed as part of the fix. Always_Remove means that the code will be removed. Always_Comment means that the code will always be commented out. Propose_Both_Choices will propose a menu with both choices.

3.8. GNATbench Trace Log

A “trace” log can be enabled for debugging GNATbench itself. (You will not need to enable this feature in normal operation.) This feature prints internal state information to a file (specified via this panel) and/or to the Eclipse console log. When AdaCore personnel ask you to enable this tracing, please also set the “Debug trace flush limit” preference to 0 to overcome any buffering of the information. See the figure below for these preference controls.

Ada GNATbench Log Preferences

If you want the trace information to go to the Eclipse console log, the log can be enabled (if necessary) by adding the “-consolelog” option to the Eclipse invocation.

3.9. Toolchains

The toolchains presented to the user are stored and persist across sessions. These toolchains are presented by the wizard when creating a new project, for example, and in the properties page. You can manage the list with this preference page.

Ada Toolchain Preferences

Note especially that you can update the list of known toolchains by pressing the Scan button, which will locate all GNAT compilers on the path.

3.10. External Commands

GNAT Studio can be invoked as an editor but is especially useful as an Ada-aware debugger and graphical interface. This preference specifies how to invoke GNAT Studio. The preference should only be changed at the suggestion of Ada personnel if a problem is encountered.

Execute command preference defines the program used to execute commands externally.

Make command preference defines the ‘make’ utility.

Ada External Commands Preferences

3.11. Tools

This page of preferences allows the user to configure the way the tools behave.

Ada Tools Preferences

For example, you can disable the automatic scanning of the toolchains’ run-time libraries for the symbols used by Code Assist. This scanning can take a long time and can therefore be disabled.

Similarly, Code Assist can be considered intrusive by touch-typists, so the facility can be entirely disabled, or if automatic invocation is enabled, the interval to delay can be specified.