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 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 Viewing Command Execution 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.
Note that Ada sources 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.
The Project menu and the Navigator 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 Build 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.
The commands "Build Project" and "Build All" will invoke the version of "gnatmake" defined by the GNAT compiler specified by the user when creating the project. Alternatively, if a foreign compiler is specified during project creation, the corresponding command specified by the user will be invoked.
Similarly, the Eclipse "Clean..." command in the Project menu invokes either the GNAT compiler's version of "gnatclean" or the command specified by the user during project creation. (The "Clean..." command offers the option to clean all projects or just a subset of selected projects.)
We describe the semantics of "Build Automatically" in a separate section of this Building chapter. See About the Build Automatically Option for the details.
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 Ada Project Explorer and Navigator project-level contextual menus.
The "Build Current Project" command will build the project using the GNAT Pro tools to determine whether a build is truly necessary. Unlike the standard Eclipse command, it will invoke the builder regardless of whether a previous build succeeded. The command invokes the same version of "gnatmake" that the standard Eclipse build command (described above) invokes, and, as a result, a full build will only occur if truly necessary.
Note that you can compile individual Ada source files instead of building executables for the entire project. See Compiling Individual Files.
The "Clean Current Project" command removes compilation products from the project. Like the standard Eclipse "Clean..." command, it calls "gnatclean" for the actual compiler defined for the project, but can also clean project hierarchies.
If a foreign compiler is specified during project creation the user-defined command will be invoked.
See Removing Compilation Artifacts for the details.
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.
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.
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. This menu entry is intended for invoking user-defined builder commands.