8. Compilation/Build

This chapter describes how to compile files, build executables, and run them. Most capabilities can be accessed through the Build top-level menu or through the Build and Run contextual menu items, as described below.

When GPS detects compiler messages, it adds entries to the Locations view, allowing you to easily navigate through the compiler messages (see The Locations View) and even to automatically correct some errors or warnings (see Code Fixing).

In source editors, compiler messages also appear as icons on the side of each line that has a message. When the pointer is placed on these icons, a tooltip appears, listing the error messages posted on the corresponding line. When GPS can automatically correct the errors, clicking the icon applies the fix. These icons are removed when the corresponding entries are removed from The Locations View.

8.1. The Build Menu

Use the build menu to access capabilities related to checking, parsing, and compiling files as well as creating and running executables. This menu is fully configurable via the Targets settings; what is documented here 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 view if no file is currently selected.

  • Build ‣ Check semantic

    Check the semantics of the current source file. Display an error message in the Messages view if no file is currently selected.

  • Build ‣ Compile file

    Compile the current file. By default, displays 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 view 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 Remove category contextual menu item or by closing the Locations view.

  • Build ‣ Project ‣ <main>

    List all main units defined in your project hierarchy, if any. Each menu item builds the selected main.

  • Build ‣ Project ‣ Build All

    Build and link all main units defined in your project. If no main unit is defined in your project, build all files defined in your project and subprojects recursively. For a library project, 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 allowing you to enter any external command. Use this item when you already have existing build scripts, make files or similar and want to invoke them from GPS. If the SHELL environment variable is defined (to, e.g. /bin/sh), the syntax used to execute the command is the one for that shell. Otherwise, GPS spawns the command without any shell interpretation.

  • Build ‣ Clean ‣ Clean all

    Remove all object files and other compilation artifacts associated with all projects related to the current one. This allows restarting a complete build from scratch.

  • Build ‣ Clean ‣ Clean root

    Remove all object files and other compilation artifacts associated to the root project but do not clean objects from other related projects.

  • Build ‣ Makefile

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

  • Build ‣ Ant

    If the ant utility is in your PATH and you have a file called build.xml in the same directory as your project file or if you have set the antfile property in the Ant section of the project properties (see The Project Properties Editor), this menu is 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, displays an entry to run the executable associated with that file. Running an application first opens a dialog where you can optionally specify command line arguments to your application. You can also specify whether the application should be run within GPS (the default) or using an external terminal.

    When running an application within GPS, a new execution view is added to the bottom area to display input and output of the application. This view is not closed automatically, even when the application terminates, so you still have access to the application’s output. If you explicitly close an execution window while an application is running, GPS displays a dialog window to confirm whether the application should be terminated.

    When using an external terminal, GPS launches an external terminal utility to perform your application’s execution and input/output. Configure this external utility in the External Commands ‣ Execute command preferences dialog.

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

    Similarly, the Run contextual menu item of a project entity contains the same entries.

  • Build ‣ Run ‣ Custom...

    Similar to the option above, except 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 that shell. Otherwise, GPS spawns the command directly without any shell interpretation.

  • Build ‣ Settings ‣ Toolchains

    Opens a dialog allowing GPS to work with two compilation toolchains. This is particulary useful when you need to compile a project with an old compiler but want up-to-date functionality from the associated tools (for example, gnatmetric and gnatcheck). See Working with two compilers.

  • Tools ‣ Interrupt

    Interrupts the last compilation or execution command. Once you interrupted the last operation, you can interrupt the previous one by selecting the same menu item again.

  • Tools ‣ Views ‣ Tasks

    The easiest way to interrupt a specific operation, whether it was the last one started or not, is to start the Task Manager via the Tools ‣ Views ‣ Tasks menu, which shows one line for each running process. Right-clicking on any of these lines allows interrupting that process.

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

8.2. The Target Configuration Dialog

GPS provides an interface for launching operations such as building projects, compiling individual files, and performing syntax or semantic checks. These operations all 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.

_images/target-configuration-dialog.jpg

This dialog is divided in two areas: on the left is a tree listing Targets and in the main area is 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 that is identical to the currently selected target.

8.2.2. The configuration panel

From the top of the configuration panel, you can select the Target model. That 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 available for all Targets.

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

    • Manually:

      The target is launched when you click on the corresponding icon in the toolbar or activate the corresponding menu item. In the latter case, a dialog is displayed, allowing final modifications of the command line.

    • Manually with dialog:

      Same as Manually, but the dialog is always displayed.

    • Manually with no dialog:

      Same as Manually, but the dialog is never displayed.

    • 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.

  • Icon:

    The icon to use for representing this target in the menus and in the toolbar. To use one of your icons, register icons using the <stock> XML customization node. (See Adding custom icons). Then use the “custom” choice and enter the ID of the icon into the text field.

  • Target type:

    Type of target described. If empty or set to “Normal”, it represents a simple target. If set to another value, it 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 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 that can be used 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 example 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 that are specific to the Model of this Target.

The full command line is displayed at the bottom. It may contain Macro Arguments. For example, 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 can launch compilation targets in the background. This means GPS launches the compiler on the current state of the file in the editor.

Error messages resulting from background compilations are not listed in the Locations or Messages views. The full list of messages are shown in the Background Build console, accessible from the Tools ‣ Consoles ‣ Background Builds menu. Error messages that 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. In both places, tooltips show the contents of the error messages.

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

GPS launches background compilations for all targets that have a Launch mode set to In background after you have made modifications in a source editor. Background compilation is mostly useful for targets such as Compile File or Check Syntax. For targets that operate on Mains, the last main 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 (i.e. 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 (see Scenario view).

When the mode is set to “default”, GPS performs the build using the switches defined in the project. When the mode is set to another value, specialized parameters are passed to the builder. For example, the gcov mode adds all the compilation parameters needed to instrument the generated objects and executables to work with the gcov tool.

In addition to changing the build parameters, changing the mode changes the output directory for objects and executables. For example, 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.

You can define new modes using XML customization, see Customizing Build Targets and Models.

The Build Mode only affects 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 if your projects need to be compiled with a specific (old) version of the GNAT toolchain while you still need 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, or computing metrics.

To configure GPS to handle two compiler toolchains, use the Build ‣ Settings ‣ Toolchains menu. This opens a dialog from which you can activate the multiple-toolchains mode.

_images/toolchains-config.jpg

In this dialog, two paths need to be configured: the compiler path and the tools path. The first is used to compile the code, while the second is used to run up-to-date tools in order to get more functionality or more accurate results. GPS only enables the OK button when the two paths are set to different locations, as that is the only case where it makes sense to enable the multiple toolchains mode.

You can also activate an automated cross-reference generation from this dialog. The cross-reference files are the .ali files generated by the GNAT compiler together with the compiled object files. The .ali files are used by GPS for several purposes, such as cross-reference browsing and documentation generation. Having those .ali files produced by a recent compiler provides more accurate results for those purposes but might cause serious problems if an old compiler were to also read those .ali files when compiling a project.

If you activate the automated cross-reference generation, GPS generates those .ali files using the compiler found in the tools path and places 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 the old toolchain’s .ali files remain untouched.

Cross-reference files generation does not output anything in the Messages view so as to not to be confused with the output of the regular build process. If needed, you can see the output of the cross-ref generation command with 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 wanting up-to-date tools on the local side, GPS does the following when both a remote compilation server is defined and the multiple toolchains mode is in use:

  • The compiler path is ignored when a remote build server is defined. All compilation actions are performed normally on the build server.
  • The tools path is used and all related actions are performed on the local machine using this path.
  • The cross-reference files are handled rsync so they do not get overwritten during local and remote host synchronizations. Otherwise, they would cause build and cross-reference generation actions to occur at the same time on the local machine and on remote server.