9.2 The Target Configuration Dialog

GPS provides an interface for launching operations like building projects, compiling individual files, performing syntax or semantic checks, and so on. All these operations have in common that they involve launching an external command, and parsing the output for error messages. In GPS, these operations are called "Targets", and can be configured either through the Target Configuration dialog, or through XML configuration. See Customizing build Targets and Models.

This dialog is divided in two areas: on the left, a tree listing Targets, and, in the main area, a panel for configuring the Target which is currently selected in the tree.

9.2.1 The Targets tree

The Tree contains a list of targets, organized by categories.

On top of the tree are three 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 GPS cannot be removed.
• The Clone button creates a new user-defined target which is identical to the currently selected target.

9.2.2 The configuration panel

On top of the configuration panel, one can select the Target model. The Model determines the graphical options available in the "Command line" frame.

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

The "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 GPS 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. See Background compilations below.
• Icon: the icon to use for representing this target in the menus and in the toolbar. To use one of your icons, you must register a icons using the <stock> XML customization node. (see Adding stock icons). Then, use "custom" choice and enter in the text field the ID of the icon.
• 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. Other custom values may be defined, and then handled via the compute_build_targets hook.

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 main GPS 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.

The "Command line" contains a graphical interface for some configurable elements of the Target, which are specific to the Model of this Target.

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", GPS will expand this to the full path to the current project. For a full list of available Macros, see Macro arguments.

9.2.3 Background compilations

GPS is capable of launching compilation targets in the background. This means that GPS will launch the compiler on the current state of the file in the editor.

Error messages resulting from background compilations are not listed in the Locations view or the Messages window. The full messages are listed in the Background Build console, accessible from the menu Tools->Console. Error messages which contain a source location indication are shown as icons on the side of lines in editors, and the exact location is highlighted directly in the editor. On both of these places, tooltips show the contents of the error messages.

Messages from background compilations are removed automatically either when a new background compilation has finished, or when a non-background compilation is launched.

GPS will launch background compilations for all targets that have a Launch mode set to In background, after modifications occur in a source editor. Background compilation is useful mostly for targets such as Compile File or Check Syntax. For targets that work on Mains, the last main that was used in a non-background is considered, defaulting to the first main defined in the project hierarchy.

Background compilations are not launched while GPS is already listing results from non-background compilations, ie as long as there are entries in the Locations View showing entries in the Builder results category.