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.
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.
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.
7.2.1.1. 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.
7.2.1.2. 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.)
7.2.1.3. 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.
7.2.2.1. 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.
7.2.2.2. 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.
7.2.2.3. 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.
7.2.2.4. 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.
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.
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:
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.
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.
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.
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.
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:
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”.
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:
If we build the project with that value for Mode we will see the corresponding debugging switches set:
If we change the value of “BUILD” to “Release”
and then rebuild we will see the different switches applied:
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):
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.
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:
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.
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:
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:
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’.
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.
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.
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.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.
