8. Compilation/Build — GPS 6.0.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- GPS 6.0.1 documentation »

# 8. Compilation/Build

This chapter describes how to compile files, build executables and run them. Most capabilities can be accessed through the Build menu item, or through the Build and Run contextual menu items, as described in the following section.

When compiler messages are detected by GPS, an entry is added in the Locations View, allowing you to easily navigate through the compiler messages (see The Locations view), or even to automatically correct some errors or warnings (see Code Fixing).

Compiler messages also appear as icons on the side of lines in the source editors. When the mouse pointer is left on these icons, a tooltip appears, listing the error messages found on this line. When GPS is capable of automatically correcting the errors, clicking on the icon will apply the fix to the source code. The icons on the side of editors are removed when the corresponding entries are removed from The Locations view.

## 8.1. The Build Menu

The build menu gives access to capabilities related to checking, parsing and compiling files, as well as creating and running executables. note that this menu is fully configurable via the Targets dialog, so what is documented in this manual are the default menus (see Build ‣ Settings ‣ Targets below).

Build ‣ Check syntax
  Check the syntax of the current source file. Display an error message in the Messages window if no file is currently selected.

Build ‣ Check semantic
  Check the semantic of the current source file. Display an error message in the Messages window if no file is currently selected.

Build ‣ Compile file

  Compile the current file.

  By default, will display an intermediate dialog where you can add extra switches, or simply press `Enter` to get the standard (or previous) switches. Display an error message in the Messages window if no file is selected.

  If errors or warnings occur during the compilation, the corresponding locations will appear in the Locations View. If the corresponding Preference is set, the source lines will be highlighted in the editors (see The Preferences Dialog). To remove the highlighting on these lines, remove the files from the Locations View using either the contextual menu (Remove category) or by closing the Locations View.

Build ‣ Project ‣ <main>
  The menu will list of all mains defined in your project hierarchy. Each menu item will build the selected main.

Build ‣ Project ‣ Build All
  Build and link all main units defined in your project. If no main unit is specified in your project, build all files defined in your project and subprojects recursively. For a library project file, compile sources and recreate the library when needed.

Build ‣ Project ‣ Compile All Sources
  Compile all source files defined in the top level project.

Build ‣ Project ‣ Build <current file>
  Consider the currently selected file as a main file, and build it.

Build ‣ Project ‣ Custom build
  Display a text entry where you can enter any external command. This menu is very useful when you already have existing build scripts, make files, ... and want to invoke them from GPS. If the SHELL environment variable is defined (to e.g. /bin/sh), then the syntax used to execute the command is the one for this shell. Otherwise, the command will be spawned directly by GPS without any shell interpretation.

Build ‣ Clean ‣ Clean all
  Remove all object files and other compilation artifacts associated to all projects related to the current one. It allows to restart a complete build from scratch.

Build ‣ Clean ‣ Clean root
  Remove all object files and other compilation artifacts associated to the root project. It does not clean objects from other related projects.

Build ‣ Makefile
  If you have the make utility in your PATH, and have a file called `Makefile` in the same directory as your project file is, or if you’ve set the makefile property in the Make section of the project properties (see The Project Properties Editor), this menu will be displayed, giving access to all the targets defined in your makefile.

Build ‣ Ant
  If you have the ant utility in your PATH, and have a file called `build.xml` in the same directory as your project file is, or if you’ve set the antfile property in the Ant section of the project properties (see The Project Properties Editor), this menu will be displayed, giving access to all the targets defined in your ant file.

Build ‣ Run ‣ <main>

  For each main source file defined in your top level project, an entry is listed to run the executable associated with this main file. Running an application will first open a dialog where you can specify command line arguments to your application, if needed. You can also specify whether the application should be run within GPS (the default), or using an external terminal.

  When running an application from GPS, a new execution window is added in the bottom area where input and output of the application is handled. This window is never closed automatically, even when the application terminates, so that you can still have access to the application’s output. If you explicitly close an execution window while an application is still running, a dialog window will be displayed to confirm whether the application should be terminated.

  When using an external terminal, GPS launches an external terminal utility that will take care of the execution and input/output of your application. This external utility can be configured in the preferences dialog (External Commands ‣ Execute command).

  The GPS execution windows have several limitations compared to external terminals. In particular, they do not handle signals like `ctrl-z` and `control-c`. In general, if you are running an interactive application, we strongly encourage you to run in an external terminal.

  Similarly, the Run contextual menu accessible from a project entity contains the same entries.

Build ‣ Run ‣ Custom...
  Similar to the entry above, except that you can run any arbitrary executable. If the SHELL environment variable is defined (to e.g. /bin/sh), then the syntax used to execute the command is the one for this shell. Otherwise, the command will be spawned directly by GPS without any shell interpretation.

Build ‣ Settings ‣ Targets
  This opens the Target Configuration Dialog. The Target Configuration Dialog.

Build ‣ Settings ‣ Toolchains
  Open a dialog allowing the configuration of GPS for working with two compilation toolchains. This is particulary useful when compiling a project with an old compiler, while wanting up-to-date functionalities from the associated tools (gnatmetric, gnatcheck and so on). Working with two compilers.

Tools ‣ Interrupt
  This menu can be used to interrupt the last compilation or run command. Once you have interrupted that last operation, you can interrupt the previous one by selecting the same menu again.

Tools ‣ Views ‣ Tasks
  However, the easiest way to interrupt a specific operation, no matter if it was started last or not, is to use the Task Manager, through the Tools ‣ Views ‣ Tasks menu. It will show one line per running process, and right-clicking on any of these lines gives the possibility to interrupt that process.

If your application is build through a Makefile, you should probably load the `makefile.py` startup script (see the menu Tools ‣ Plug-ins).

## 8.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. 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.

### 8.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.

### 8.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. (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.

### 8.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 ‣ Consoles ‣ Background Builds. 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.

## 8.3. The Build Mode

GPS provides an easy way to build your project with different options, through the mode selection, located in the Scenario view (Scenario view).

When the mode is set to default, the build is done using the switches defined in the project. When the mode is set to another value, then specialized parameters are passed to the builder. For instance, the gcov Mode adds all the compilation parameters needed to instrument the produced objects and executables to work with the gcov tool.

In addition to changing the build parameters, the mode has the effect of changing the output directory for objects and executables. For instance, objects produced under the debug mode will be located in the `debug` subdirectories of the object directories defined by the project. This allows switching from one Mode to another without having to erase the objects pertaining to a different Mode.

It is possible to define new modes using XML customization, see Customizing build Targets and Models.

Note that the Build Mode affects only builds done using recent versions of gnatmake and gprbuild. The Mode selection has no effect on builds done through Targets that launch other builders.

## 8.4. Working with two compilers

This functionality is intended for people whose projects need to be compiled with a specific (old) version of the GNAT toolchain, while still desiring to take full advantage of up-to-date associated tools for non-compilation actions, such as checking the code against a coding standard, getting better cross-reference browsing in GPS, computing metrics and so on.

GPS now allows you to handle this case. To configure GPS to make it handle two compiler toolchains, you need to use the Build ‣ Settings ‣ Toolchains menu. This will open a dialog where you can activate the multiple-toolchains mode.

In this dialog, two paths need to be configured: the compiler path and the tools path. The first one is used to actually compile the code, while the second one is used to run up-to-date tools to get more functionalities or accurate results.

Note that GPS will only enable the OK button when the two paths are set to different location, since otherwise it does not make sense to enable the multiple toolchains set up.

From this dialog, you can also activate an automated cross-reference generation. The cross-reference files are the .ali files generated by the GNAT compiler together with the compiled object. Those files are used by GPS for several functionalities, such as cross-reference browsing or documentation generation. Having those .ali files produced by a recent compiler helps having more accurate results with those functionalities, but might interract badly with an old compiler also reading those .ali files for compiling a project.

If the automated xref generation is activated, then GPS will generate those .ali files using the compiler found in the tools path, and place them in a directory distinct from the one used by the actual compiler. This allows GPS to take full benefit of up-to-date cross-reference files, while keeping the old toolchain happy as its .ali files remain untouched.

Note that the cross-reference files generation does not output anything in the “Messages” window, so as to not confuse the output of the regular build process. If needed, you can see the output of the cross-ref generation command by selecting the Tools ‣ Consoles ‣ Auxiliary Builds menu.

### 8.4.1. Interaction with the remote mode

The ability to work with two compilers has impacts on the remote mode configuration: paths defined here are local paths, so they have no meaning on the server side.

To handle the case of using a specific compiler version on the remote side while still wanting up-to-date tools, the following behavior is applied when both a remote compilation server is defined, and the multiple toolchains mode is activated:

- The compiler path is ignored when a remote build server is defined. All compilation actions are then performed normally on the build server.
- The tools path is however taken into account, and all related actions are performed on the local machine using this path.
- The cross-reference files are taken care of by the rsync mechanism so that they don’t get overwritten during local and remote host synchronisations, as build and cross-reference generation actions occur at the same time, on the local machine and on the distant server.

### Navigation

- index
- modules |
- next |
- previous |
- GPS 6.0.1 documentation »