7. Building

7.1. Project Builder Command Menus

GNATbench provides project-level builder commands in two menus: the Project menu and the project contextual menus of the GNAT Project Explorer and the Navigator. These commands include the standard project builder commands defined by Eclipse, with additional builder commands defined by GNATbench. Other “builder” commands are also included, such as those that clean the project of compilation products.

We describe the semantics of the standard and additional commands in Project Builder Command Semantics. This section describes the menu entry locations.

7.1.1. Project Menu

The Project menu on the menubar defines the standard Eclipse project build commands, Build All through Build Automatically, as shown in the following figure. The GNATbench project-specific builder extensions appear further down.

project builder menu

7.1.2. Contextual Menus

The contextual menu of the GNAT Project Explorer (and the Navigator) includes the standard Build Project command, as shown below. It appears in the standard “project” section of the menu, just below the import/export menu entries. This is the same command as in the Project menu on the menubar so it will also be disabled when Eclipse considers a build unnecessary.

Note that you must right-click on the name of the project itself to get to the menu with the project builder commands, not on some entity within the project.

The GNATbench extensions to the project contextual menus of the GNAT Project Explorer and the Navigator appear near the bottom of the contextual menus. These extensions include those added to the Project menu as well as two additional builder commands that are less frequently used.

contextual project builder menu

7.2. Project Builder Command Semantics

GNATbench provides the standard project builder commands defined by Eclipse, with some changes for the sake of building in the context of a distinct linking phase, and augments them with builder commands specific to a given project. All these commands display their execution in the Console view and any compilation warnings and errors are reported in the Problems View. The builder commands defined by GNATbench are typically used in preference to the Eclipse-defined commands.

The project builder commands build the project based on the definition within the GNAT project file (*.gpr file) controlling the GNATbench project. For example, if one or more main programs are defined by the GNAT project file, building the project creates the executables corresponding to those main subprograms. As an alternative example, the GNAT project file may describe a library project, in which case the library is created when the project is built.

GNAT project files may define a project hierarchy, when the so-called “root” project imports other GNAT project files via “with clauses”. When a root project is built, all the imported projects will also be built, as necessary, using the compilation switches defined by the root project. Thus, for example, an imported library project might be built along with executable images requiring that library in the root project.

See GNAT Projects for a description of GNAT projects and project files.

Note that Eclipse projects may reference other Eclipse projects. Since a GNATbench project is also an Eclipse project, project hierarchies need not be contained within one Eclipse project.

Build steps and resulting messages are displayed on the standard Eclipse Console view in a subconsole specific to the command. You can show this view using the standard Eclipse Window -> Show View command if the Console is not already open. See Ada Build Console for the details of using the builders’ subconsoles.

The progress indicator at the lower right of the Eclipse window will show the command as it runs, including the percentage complete. You can also interrupt build commands using the Progress view controls.

Note that Ada source files are saved automatically when a project is built if they are within that specific project and if they have been altered but not yet saved. This effect is controlled by a preference and is enabled by default. See the Editor preference page for the location of the controlling preference.

7.2.1. Standard Eclipse Build Commands

The Project menu and the GNAT Project Explorer contextual menu provide the standard Eclipse project commands and GNATbench implements the standard semantics. These are the menu entries “Build All” through “Build Automatically” in the Project menu and “Build Project” in the contextual menu. See Project Builder Command Menus for the locations and content of these menus.

The various build commands and the “Clean…” command operate based on the build history, that is, they perform their action only if Eclipse believes them necessary. Indeed, the build commands will be disabled whenever a build previously succeeded and nothing has changed to make Eclipse believe another build is necessary. Build Project and Build All

The commands “Build Project” and “Build All” will invoke the GNAT builder for the GNAT toolchain specified by the user when creating the project. Alternatively, if a user-defined toolchain is specified during project creation, the corresponding command specified by the user will be invoked. Clean…

Similarly, the Eclipse “Clean…” command in the Project menu will invoke the GNAT cleaner for the GNAT toolchain specified by the user when creating the project. (The “Clean…” command offers the option to clean all projects or just a subset of selected projects.) Build Automatically

We describe the semantics of “Build Automatically” in a separate section of this chapter. See About the Build Automatically Option… for the details.

7.2.2. GNATbench Project-Specific Builder Commands

GNATbench defines additional builder commands that provide the convenience of operating specifically on the currently selected project. These enhancements appear in the next section down in the Project menu and at the bottom of the GNAT Project Explorer project-level contextual menu. Clean Current Project

The “Clean Current Project” command removes compilation products from the project. Like the standard Eclipse “Clean…” command, it calls the cleaner (gnatclean or gprclean) for the toolchain defined for the project, but can also clean project hierarchies.

If a user-defined toolchain is specified during project creation the user-defined command will be invoked.

See Removing Compilation Artifacts for the details. Rebuild Current Project

The “Rebuild Current Project” command first “cleans” the root project and then invokes the builder. A full build of the root project is thus performed. Note that rebuilding an entire project hierarchy requires first cleaning the entire project tree using the Clean Current Project/Tree command. Analyze Project Sources

The “Analyze Project Sources” command will check all the sources in the project, including those that have not changed, for syntax and semantic errors. Any warnings and errors are sent to the problems view as usual. Note that this command does not create an executable.

The “Analyze Project Sources” command will also generate the required information to support those browsing and navigation commands that require it, without also producing object code.

Note that you can analyze individual Ada source files instead of analyzing the entire project. See Analyzing Individual Files. Invoke Makefile In Target

The “Invoke Makefile In Target” command allows you to invoke user-defined builder commands. We cover the details of this command in a separate part of this “Building” chapter. See User-Defined Builder Commands for the details.

Note that there is no compelling reason to use “Invoke Makefile In Target” to invoke the builder commands predefined by Eclipse and GNATbench, unless, of course, those commands have been changed by the user in the makefile. This menu entry is primarily intended for invoking user-defined builder commands that GNATbech and Eclipse do not invoke.

7.3. Project Builder Key Bindings

The GNATbench builder commands do not have keys bound to them, as shown in the figure below. Eclipse itself binds Ctrl-B to the Build All project command and it will indeed build all GNATbench projects in addition to any other non-Ada projects. Note the additional project-specific commands further down in the menu that are added by GNATbench.

project builder menu

Defining global, “MDI-level” key bindings (such as Ctrl-B) is best left to the user because many plug-ins are likely to be loaded in an Eclipse installation and each is likely to define global key bindings. A great many bindings are thus possible but when these bindings conflict, none of them take effect, except for bindings defined directly by Eclipse itself. The user, however, can unbind key bindings and redefine them as desired, including those defined by Eclipse. Therefore, we have not bound builder commands to keys.

You may define your own bindings to all these builder commands, if desired. To define or redefine key bindings, use the Window -> Preferences menu, then expand the General category and select the Keys page.

In contrast to global key bindings, context-specific bindings do not conflict with one another and therefore GNATbench defines many such bindings. For example, editor commands are language-specific so they can have identical bindings without conflicting. These bindings are discussed in the chapters corresponding to the specific capabilities.

7.4. About the Build Automatically Option…

The Project menu on the menubar defines the standard Eclipse project build commands, including “Build Automatically”. (See the figure below for the location of the menu entry.) Build Automatically is actually an option, not a command, and will have a check-mark next to it when it is enabled.

project builder menu

When the Build Automatically option is enabled and an Ada source file is changed and saved (or after the overall project is cleaned), the builder is automatically invoked.

If the project is clean (or has never been built in the first place), Eclipse invokes a full build and an executable will be generated if possible.

However, a full build is not invoked when Eclipse does not consider it to be required. For example, after a full build, changing a single file invokes an incremental build. In this mode the compiler will perform syntax and semantic analysis on the unit in the changed source file and all of its dependent units, transitively, but the binder or linker phases are not performed. Errors are thus detected as early as possible but without the expense of a full build.

Note that the Ada editor has a preference, enabled by default, to save altered project source files before a build begins. If multiple source files are altered but not yet saved and the Build Automatically option is enabled, saving any one of those files will invoke the builder and thus all of the altered source files in that project will be saved as well.

7.5. Ada Build Console

When the builder is invoked (including when cleaning), the Console view is made visible and a project-specific builder “subconsole” is shown. The focus is not given to the Console view, the view is just made visible so that work in another view or editor can continue uninterrupted. Build steps and any resulting messages are displayed in the subconsole as the command executes.

The subconsole will have a title of “Ada build” followed by the name of the project enclosed within square brackets. For example, in the following figure, the project Ms1553_Demo has completed a full build:

Ada builder subconsole

You can use the standard contextual menu within the subconsole to copy the contents, clear it, and so forth.

There may be multiple build subconsoles within the Console view since multiple projects can exist and be built independently. You can choose among these subconsoles by clicking on the down-arrow next to the “Console” icon and selecting from those that appear in the popup menu. The Console icon is the fourth from the left in the following figure and looks like a computer monitor. This figure also shows the console selection popup menu containing two open subconsole names. Note that the Console icon will be disabled if no other subconsoles exist to be selected.

Ada builder subconsole showing selection menu

You can traverse through the various open subconsoles by simply clicking directly on the Console icon.

Note that if another view within the same group containing the Console view already has the focus, for example if the Problems view or the Scenario Variables view is being examined, the specific project’s build subconsole is not brought to the front so that working with the other view in that group is not interrupted.

7.6. Compiling Individual Files

GNATbench defines menu entries for compiling individual files in addition to building complete projects.

Compilation steps and messages are displayed on the standard Console view in a subconsole specific to the command. You can show this view using the standard Eclipse Window -> Show View command if the Console is not already open. See Ada Build Console for the details of using the builders’ subconsoles.

The progress indicator at the lower right of the Eclipse window will show the command as it runs, including the percentage complete.

7.6.1. Within the Ada Editor

The GNATbench Ada editor extends the contextual menu with an entry “Compile Ada File” (shown in the figure below) that will attempt to compile the compilation unit in that file. Note the key binding in this context.

compile file editor menu

7.6.2. Within the GNAT Project Explorer

You can also compile individual Ada source files using the contextual menu of the file nodes in the GNAT Project Explorer. The menu command is “Compile Ada File(s)”.

Right-click on a file node in the Project Explorer to get the file-specific contextual menu, as opposed to the project-level contextual menu.

In addition, you can compile multiple Ada source files by selecting several nodes before invoking the command. The figure below illustrates selecting several files within the GNAT Project Explorer for compilation.

compiling multiple files in explorer

7.7. Analyzing Individual Files

GNATbench provides a capability to analyze an individual source file as an alternative to analyzing all the source files in the project. Like the project-level command, this command checks syntax and semantics but will also generate the required information to support those browsing and navigation commands that require it, without also producing object code or an executable.

Analysis results are displayed on the standard Eclipse Console view in a subconsole specific to the command. You can show this view using the standard Eclipse Window -> Show View command if the Console is not already open. See

Ada Build Console for the details of using the builders’ subconsoles.

The command is in the contextual menu of the Ada editor and is named “Analyze Ada File” (as shown in the figure below). Note the key binding.

analyze file editor menu

7.8. Removing Compilation Artifacts

All compilation products specified implicitly or explicitly by the GNAT project file (*.gpr file) can be removed using the project cleaning menu defined by the Project menu and the contextual menus of the GNAT Project Explorer and Navigator. Specifically, the object files (*.o), “ali” files (*.ali), and executable images (e.g., *.exe on Windows) can be removed.

The menu entry is named “Clean Current Project” and is actually two submenus: one to clean the currently selected project root, and one to clean the root as well as the “tree” of projects imported by the root project. (Imported projects are those named in “with clauses” in a project’s GNAT project file.) These two submenu entries are shown in the following figure:

cleaning projects

7.9. Building Projects with Scenarios

GNAT project files have the concept of scenario variables that allow considerable flexibility in controlling how the tools build an executable, among other possible uses. (See Scenario Variables for details on scenario variables, and GNAT Projects for the details of GNAT project files.) You can define, for example, different scenarios for debugging and releases, in which optimization and symbolic information are either present or not, respectively.

GNATbench provides the Scenario View for managing scenario variables. The idea is that you can view and control the build by changing the values of the scenario variables within this view. (See Scenario Variables View for details.)

Note that scenario variable settings persist across Workbench sessions so there is no need to set them again whenever Workbench is started or a closed project is re-opened.

The wizard that created our new project also created the corresponding GNAT project file for us. It is shown below. Note the scenario variable named “Mode”.

project file created by wizard with scenarios

The variable Mode has two possible values because of its type: “Release” and “Debug”. (These values are case-sensitive because they are strings.) As you have guessed, these two values represent two different build scenarios. “Release” corresponds to the scenario in which you build for actual delivery. The “Debug” scenario is for development and testing. Therefore, these scenarios require different switches to be applied and this fact is reflected in the content of the project file. Note in particular the switches set in the package Compiler depending on the value of Mode. You will see these switches applied in the build console.

The initial value of Mode is “Debug” because that is the default:

scenario view showing Debug selection

If we build the project with that value for Mode we will see the corresponding debugging switches set:

content of build console after successful build

If we change the value of “BUILD” to “Release”

scenario view showing Release selection

and then rebuild we will see the different switches applied:

content of build console after changing BUILD to Release

7.10. Cross Compiling

GNATbench supports building systems for execution on the host machine as well as on an embedded computer. The difference is merely a matter of selecting the appropriate cross compiler when creating the project.

In particular, the new-project wizard requires you to specify the toolchain, by either selecting from a predefined list or by manually entering the name and commands for a new toolchain. Multiple native and cross toolchains may be in the list, as depicted in the figure below (not all appear):

cross compilers offered by wizard

See Creating New Projects for the details of selecting toolchains when creating projects.

7.11. Using Multiple Toolchains

When creating a new project, the wizard requires you to specify at least one toolchain, but you can select more than one. Both native and cross toolchains may be selected. You can also change your toolchain selections after a project is created. See Creating New Projects for the details of selecting toolchains when creating projects and changing them later.

The figure below shows the Properties dialog presenting the GNATbench Properties page. Note that both a native and a cross toolchain are selected, and that the cross compiler will be used by default.

multiple toolchains selected in properties

When multiple toolchains are selected, the GNATbench wizard alters the GNAT Project file (the “gpr file”) so that a new scenario variable named “Target” is declared, with possible values representing each selected toolchain. The wizard also alters the IDE package within the project file so that the “Target” scenario variable controls which toolchain will be applied. The following figure illustrates these alterations:

gpr file with multiple toolchains available

The wizard makes the necessary additions and alternations to the gpr file. You use the Scenario Variables view to select which toolchain to apply, just as would be done for any other scenario variable.

toolchain selection scenario var view

7.12. Building with Makefiles

When requested by the user, GNATbench can use a project-specific makefile to drive project builds. The makefile is created by the wizard when creating the project. (See Creating New Projects for the details of creating a new project.)

Naturally, driving the build with a makefile requires the ‘make’ utility to be installed and on the path. GNATbench does not include the ‘make’ utility. You are responsible for installing it if you choose to use it.

You can revisit the choice of whether to drive the build with a makefile, after a project is created, by editing the project properties. To do so, invoke the Properties menu entry for the given project and then select the “GNATbench Properties” page. There is a check-box controlling the option:

GNATbench properties showing makefile option

Although GNATbench does not require a makefile and the corresponding make utility, there are two primary reasons to allow makefiles to be used. The first reason is that developers can use a script to build their executables. A script is a means of demonstrating repeatable executable image construction, a typical requirement, for example, of high-integrity applications. Developers can reference the makefile as part of their demonstration. The second reason to allow a makefile is so that project-specific user-defined build commands can be defined. These commands might be required, for example, to do some extra setup steps not known to the GNAT compiler. We illustrate this situation in User-Defined Builder Commands.

7.12.1. Modifying the “make” utility name

The ‘make’ utility name can be changed using the “Ada - External Commands” preferences page. The preferences dialog is accessible via the Window->Preferences menu group.

7.12.2. Modifying the Makefile

As generated, the makefile only invokes the build commands and does not use any additional ‘make’ capabilities such as defining dependencies between files and makefile targets. For example, here is a sample makefile generated by the new-project wizard:

sample basic makefile

The project-specific makefile and GNAT project file work together to define the effective command. That fact is reflected in the use of the “-P” switch followed by the macro variable that references the GNAT project file (“gpr file”) in the figure above.

You can edit the makefile to use as much of the ‘make’ tool capabilities as you feel appropriate, and thus perhaps put less in the GNAT project file, but doing so will reduce interoperability with GNAT Studio. GNAT Studio is also conceptually based on GNAT project files and in general the two IDE’s can share GNAT project files without changes.

If you do edit the makefile, for whatever reason, be sure to retain the existing target names. These targets are used by GNATbench when invoking the various build-related commands. You can change what they do, just don’t delete them.

7.12.3. Makefile Name and Location

GNATbench will read the Make package of the GNAT Project file, if present, to determine the name and location of the makefile to use. If the makefile name is not specified, ‘make’ will be launched without a makefile file name argument, in which case the default name “Makefile” will be used. Also by default, the file is assumed to be in the same location as the GNAT Project (gpr) file.

The following figure contains an example Make package in a project file. Here we have specified that the makefile file is named “mymakefile” and that it is located in a folder named “control”. Note that any name other than “Makefile” will not be recognized by the Outline view as a genuine makefile, although it will be properly processed as such by ‘make’.

package make in project file

When a builder command is invoked, the specified makefile is named explicitly as a parameter to make, as shown in the following figure (in which the “rebuild” command has been issued). Note in particular the second line, where ‘make’ is invoked with the “-f” switch naming the user-specified makefile.

build console showing named makefile

7.13. User-Defined Builder Commands

GNATbench can optionally use a project-specific makefile to drive project builds. (See Building with Makefiles for the details.) User-defined builder commands are defined in these makefiles.

7.13.1. Defining Commands

You create a user-defined command by adding a new makefile target and associated tool invocation to an existing makefile. In the following figure, we have added a command that assembles a small file written in assembly language and compiles an Ada source file. This new command (makefile target) is named “setup” and appears at the end of the makefile.

sample makefile with user-defined command

We could have used the ‘make’ dependency capability to have this command executed automatically when necessary, but in this simple example the user will invoke the command when first building the project.

7.13.2. Invoking User-Defined Commands

The “Invoke Makefile Target” command allows you to invoke the low-level commands represented by the makefile targets. All targets defined by the makefile are presented as submenu entries, including user-defined targets. For example, the following figure illustrates selection of the user-defined target named “setup”:


Simply select the name of the target to invoke it. The command execution and any resulting messages will be displayed in the project-specific console.

7.14. Build Mode

GNATbench provides an easy way to build your project with different options, through the Mode selection, located in the main toolbar. It can be displayed enabling “GNATbench Build Mode Menu” command group through Window -> Customize Perspective… -> Command Groups Availability menus.

When the Mode selection is set to default, the build is done using the switches defined in the project. When the Mode selection 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 selection 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.

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.

7.15. 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 Ada Builder Targets preference page, so what is documented in this manual are the default menus. Use “GNATbench Build Toolbar, Contextual or Menubar Menus’ command groups through “Window -> Customize Perspective.. -> Command Groups Availability” menu to enable these menus visibility.

See the Builder Targets Editor

7.15.1. Check Syntax

Check the syntax of the current source file. Display an error message dialog if no file is currently selected.

7.15.2. Check Semantic

Check the semantic of the current source file. Display an error message dialog if no file is currently selected.

7.15.3. Compile File

Compile the current file. Display an error dialog if no file is selected.

If errors or warnings occur during the compilation, the corresponding locations will appear in the Problems View.

7.15.4. Project Build <main>

The menu will list of all mains defined in your project hierarchy. Each menu item will build the selected main. 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. Compile All Sources

Compile all source files defined in the top level project. Build <current file>

Consider the currently selected file as a main file, and build it. 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 GNATbench.

7.15.5. 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. Clean Root

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

7.15.6. 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 GNATbench (the default), or using an external terminal.

When running an application within GNATbench, the Messages [$PROJECT] console is displayed in the Console view. It is where inputs and outputs of the launched application are 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 the Console view while an application is still running, the application will still run in background. To terminate it use to Cancel Operation button of this job in the Progress view. The Progress view can be displayed using “Windows /Show View / Other… / General / Progress” menu or clicking the “Shows background operations in Progress view” button displayed the the right of the status bar.

When using an external terminal, GNATbench 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 GNATbench execution Messages in Console view have several limitations compared to external terminals. In particular, it displays only the latest launched application user interface and it 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. Custom…

Similar to the entry above, except that you can run any arbitrary executable.

7.16. Troubleshooting Builder Problems

7.16.1. Eclipse and CDT Version Mismatch or Missing

You must install the latest versions of Eclipse, the corresponding version of the C/C++ Development Tools (CDT), and the AdaCore compilation toolset *before* installing the GNATbench plug-in. If these tools are not installed, with the proper versions, behavior is generally unpredictable.

See Prior Required Tool Installations for the current versions required.

7.16.2. Conflicting Plug-Ins

In all probability, you must remove or completely disable any other Ada development plug-in that includes the functionality that GNATbench provides. In particular, any plug-in that defines a project builder for Ada source code will likely prevent correct operation of GNATbench, and vice versa.