1. Getting Started

1.1. Prior Required Tool Installations

Before you can use GNATbench you must install the required environments and tools.

The GNATbench plug-in for Eclipse requires the following to be installed prior to installing GNATbench itself:

For 64-bit Linux or Windows one of the following versions Eclipse 2018-09 (4.9) Eclipse 2019-06 (4.12) Eclipse 2019-12 (4.14) Eclipse 2020-03 (4.15) Eclipse 2020-06 (4.16)

The C/C++ Development Tools (CDT) plug-in for Eclipse, compatible with the version of Eclipse chosen. This should be the version released along with the version of Eclipse you are installing, or any compatible updates for it.

The official JRE from Oracle or Open JDK. GNATbench was not tested on IBM Java. Eclipse 2018-09 (4.9) requires JER-8. All others supported Eclipse versions requires JRE-8 or JRE-11.

Specifically, you must install Eclipse, the C/C++ Development Tools (CDT), and the AdaCore compilation tool-set before installing the GNATbench plug-in. For the CDT, install the version required by the version of Eclipse you are using. The easiest and most reliable approach is to install the Eclipse bundle that automatically includes the CDT, however you can also install them individually.

1.2. Conflicting Plug-In Removal

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.

1.3. Installing GNATbench

The file gnatbench-<version>-<platform>-bin.zip is an archive to be installed through the regular Eclipse installation mechanism.

Open Eclipse or Workbench and select ‘Help -> Install New Software’ (if this menu is not available, it can be added through the Eclipse perspective customization panel).

Click on the ‘Add’ button to add a repository. Select ‘Archive’ and navigate to the zip file downloaded from AdaCore. The Location field will then reference that file. You can optionally enter a repository name for future reference, such as “GNATbench” (without the quotes). Click ‘OK’.

The Eclipse installer will then offer the choice of different versions of GNATbench for installation. For Eclipse, select ‘AdaCore Plugins for Eclipse/CDT’. Be certain to NOT also select an other version!

Click ‘Next’ and follow the installation wizard to completion. During the installation process, a dialog can be raised asking if you trust the AdaCore certificates. Check the mark next to the GNATbench certificate and press ‘OK’.

Note: the GNATbench Ada Development User Guide could be accessed after installation, with all other User Guides, via the “Help -> Help Contents” menu entry.

1.4. Before Browsing and Navigating the Code

You need to compile the code for full functionality, such as Ada editor hyper-links, to be available. Only partial support will be available until that occurs. Please see the ‘Crucial Setup Requirement’ section in the ‘Browsing and Navigation’ chapter of the GNATbench User Guide for details.

1.5. Verifying Correct GNATbench Installation

To verify that GNATbench has been installed into Eclipse, start with the Eclipse Help menu. First, select Help and then “About Eclipse” at the bottom of the selections. Then press the “Installation Details” button at the lower left of the resulting dialog box. Another pop-up dialog box will appear, with tabbed pages showing the installed software, features, plug-ins, installation history, and configuration. Click on the “Plug-ins” tab to show all the installed plug-ins. You should see a number of plug-ins with “AdaCore” shown in the Provider column. (Click on the Provider column header to sort by provider names.) If you see the AdaCore plug-ins, installation is likely fine. If not, installation has not occurred or did not complete successfully.

The list of plug-ins will look something (but not exactly) like the figure below.

plug-ins list

Finally, verify that GNATbench is ready to use installed GNAT compilers.

At least one GNAT compiler should be installed to use GNATbench. Please note that no GNAT compiler is installed during GNATbench installation.

If a GNAT compiler was previously installed, check that any required changes to environment during GNAT installation have been done. As an example of such changes, the GNAT tools path should be added to the PATH environment variable. Otherwise, a GNAT compiler installation is requested and any required changes to environment variables must be performed. When a new compiler is installed, a workbench restart may be required to use the latest environment.

Successfully detected compilers are displayed in the /Ada/Toolchains preferences page accessible from the /Window/Preferences menu by selecting the Ada entry and then Toolchains.

toolchains list

If no toolchains are displayed, click on “Scan” button to start a toolchain scan.

1.6. Introduction

GNATbench supports sophisticated Ada-aware editing and browsing, code generation using GNAT, and Ada-aware debugging.

1.7. Intended Audience

This User’s Guide is intended for Ada software developers using the GNAT Ada tools to develop applications within Eclipse.

1.8. Scope

This User’s Guide describes how to use the GNATbench Ada plug-in for Eclipse. Specific help is provided for configuring projects, building systems, and debugging; please see the corresponding sections for details.

For help with the GNAT compiler and associated tools themselves, see the GNAT documentation corresponding to the specific compiler used.

1.9. For Additional Information and Help

Additional help and information is available online from AdaCore via the GNAT Tracker web interface.

1.10. Creating and Building A Basic Native Project

In this tutorial we will create and build a fully executable simple “Hello World” project.

Creating a new project for Ada development is easy with GNATbench. The wizard will create and configure the project for us, and invoking the builder is simply a matter of selecting a command.

1.10.1. Creating and Configuring the Project

The first step is to invoke the wizard to create a new Ada project. Using the Ada toolbar addition, click on the “New Ada Project” icon, as shown in the following figure:

new-project wizards on toolbar

The first page of the new-project wizard (shown in the next figure) will appear. Enter the name of the new project. We have named this one “hello”. We have the option of locating the new project in the default workspace or elsewhere in the file system. We’ll take the default. Press Next.

tutorial\_native\_wizard\_page1

The next page asks us to specify the unit name of the GNAT project (not the file name), that is, the name within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, for example, by substituting underscores for dashes. If the Eclipse project name is already a legal Ada identifier that name is used unchanged, as in this case:

tutorial project unit name dialog

In the next page we enter the name of the Ada main subprogram – not the file name – and have the wizard generate the file containing that unit. We arbitrarily name the unit “hello” and have it generated as a program that prints “Hello World!” when executed.

new project wizard ada config page2

On the next page we then choose the locations for our source files and object files. The defaults, as shown below, will have all source files in the “src” folder, all object and “ali” files in the “obj” folder, and the executable also in the “obj” folder.

new project wizard ada config page3

On the next page we choose the specific toolchain. The default native compiler is already selected, as shown below.

new project wizard ada config page4

Press Finish. The new project will be created and you will see it in the GNAT Project Explorer, as in the following image. Note that we have expanded the “src” directory to show the source file within.

tutorial\_created\_native\_project

The source file contains the main subprogram. This file will have the name we specified, “hello.adb”, and will contain a procedure with that unit name:

tutorial main subprogram in editor

In a real application we would alter the content of the main subprogram. It is a buildable subprogram, though, without any changes, so for the purpose of this tutorial we can leave it as it is.

1.10.2. Building the Project

Now that the setup has completed we are ready to do the full build. In the GNAT Project Explorer, right-click on the project node and select “Build Project”.

tutorial\_native\_project\_builder\_menu

A successful build will appear in the Console view:

tutorial\_native\_build\_console\_success

1.10.3. Congratulations!

That’s it! You have created and built a project using GNATbench for Eclipse.

1.11. Creating and Building An Embedded Computer Project

In this tutorial we will create and build a fully executable (simple) project. We have chosen to create a project for an embedded computer because it highlights some of the additional capabilities provided by GNATbench; the process is almost exactly the same for creating executables for native execution on the host computer.

Creating a new project for Ada development is easy with GNATbench. The wizard will create and configure the project for us, and invoking the builder is simply a matter of selecting a command.

1.11.1. Creating and Configuring the Project

The first step is to invoke the wizard to create a new Ada project. Using the Ada toolbar addition, click on the “New Ada Project” icon, as shown in the following figure:

new-project wizards on toolbar

The first page of the new-project wizard (shown in the next figure) will appear. Enter the name of the new project. We have named this one “ppc_elf_demo”. We have the option of locating the new project in the default workspace or elsewhere in the file system. We’ll take the default. Press Next.

new project name in wizard page1

The next page asks us to specify the unit name of the GNAT project (not the file name), that is, the name within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, by substituting underscores for dashes for example. If the Eclipse project name is already a legal Ada identifier that name is used unchanged, as in this case:

tutorial project unit name dialog

In the next page we enter the name of the Ada main subprogram – not the file name – and have the wizard generate the file containing that unit. We arbitrarily name the unit “hello” and have it generated as a program that prints “Hello World!” when executed.

new project wizard ada config page2

On the next page we then choose the locations for our source files and object files. The defaults, as shown below, will have all source files in the “src” folder, all object and “ali” files in the “obj” folder, and the executable also in the “obj” folder.

new project wizard ada config page3

On the next page we choose the specific toolchain. We also enable the use of “make” to build the project. This usage is strictly optional – gprbuild could be used instead – but we want to illustrate makefile use as well in this example. The page with this set of selections is shown below.

new project wizard ada config page4

Press Finish. The new project will be created and you will see it in the GNAT Project Explorer, like so:

created project in Project Explorer

If you see files with names beginning with a dot, such as “.project”, you can hide them by customizing the view. First, select the Customize View menu by clicking on the View Menu icon (the down-pointing arrow head at the far right of the GNAT Project Explorer view):

customize view menu entry

In the Customize View dialog, put a check-mark next to the “.* resources” option to hide all resources with names beginning with a dot, like so:

customize view hiding dot resources

As a result, all files with that naming scheme will be hidden in the view.

In the view of the project (see the figure below), note the presence of the files named “Makefile” and “ppc_elf_demo.gpr”. These are the makefile and GNAT project file, respectively. These files may be edited but they must not be deleted.

created project in Project Explorer

Also note the file containing the main subprogram underneath the source folder (we expanded it to show the file). This file will have the name we specified, “hello.adb”, and will contain a procedure with that unit name:

tutorial main subprogram in editor

In a real application we would alter the content of the main subprogram. It is a buildable subprogram, though, without any changes, so for the purpose of this tutorial we can leave it as it is.

1.11.2. Modifying the GNAT Project File

We need a linker script to link the executable because this is a bare-board application. Hence we must tell the linker how to find this script so we modify the GNAT project file created by the wizard.

The original project file looks like this:

original project file from wizard

We then add the Linker package for the sake of the script:

modified project file

We’ve also added a reference to an object file named “putchar.o” that will be explained momentarily.

1.11.3. Importing the Script and Sources

We also have to insert this script into the workspace project. We have a stored copy on disk so an easy way to get it into the project is to use the Import… wizard from the Navigator and get the script from the file system.

We also need to import an assembly language source file. This assembly source file contains startup code necessary for the application to run on the bare machine.

Similarly, we need the source files for an Ada procedure that defines how to output a character using the hardware on the bare board. That Ada procedure is the “putchar” routine mentioned earlier in the Linker package. The source files are located in the “extra_rtl” subdirectory.

We import all of them by selecting “File System” under the “General” category and pressing Next.

importing the assembly source file

After browsing to the location and selecting the two individual files required, we also select the directory named “extra_rtl” so that the putchar sources will be imported too. Then simply press Finish and the files will be imported into the project.

importing the linker script

After importing the files, the project will now look like this:

project view after importing

1.11.4. Adding A Command

Now that we have the files, we need to compile them, once, before building the entire application. We will add a new command and name it “setup” since we only need to compile the source files once. In practice we would have the Makefile automatically invoke this command when necessary, but we will do it manually for the sake of this tutorial.

Therefore, we modify our “Makefile” file to add a “setup” command. This command will be added to the bottom of the Makefile:

modified makefile containing the new command

Note the comment above the target name. This comment will appear in a dialog box to serve as a reminder of what the new command does.

1.11.5. Invoking the User-Defined Command

We can now invoke the Project menu (or the Explorer’s contextual menu) and choose “Invoke Makefile Target” to get the list of user-defined target commands available. Select the name “setup” among the listed build target names and press Invoke.

invoking the makefile target selection dialog

Command execution will be displayed in the console.

tutorial target setup in build console

If we then expand the “obj” directory in the GNAT Project Explorer we see the resulting files:

resulting object files in the project objs dir

1.11.6. Building the Project

Now that the setup has completed we are ready to do the full build. In the Eclipse menubar, open the Project menu and select “Build Project”.

project builder menu

A successful build will appear in the Console view:

content of build console after successful build

1.11.7. Congratulations!

That’s it! You have created and built a project for an embedded computer using GNATbench for Eclipse.

1.12. Using GPRbuild To Build An Embedded Computer Project

In this tutorial we will create and build a fully executable bare-board project using GPRbuild. In particular, we will build the executable from sources in Ada, C, and assembler.

Creating a new project for Ada development is easy with GNATbench. The wizard will create and configure the project for us, and invoking the builder is simply a matter of selecting a command.

1.12.1. Creating and Configuring the Project

The first step is to invoke the wizard to create a new Ada project. Using the Ada toolbar addition, click on the “New Ada Project” icon, as shown in the following figure:

new-project wizards on toolbar

The first page of the new-project wizard (shown in the next figure) will appear. Enter the name of the new project. We have named this one “gprbuild-demo”. We have the option of locating the new project in the default workspace or elsewhere in the file system. We’ll take the default. Press Next.

new project name in wizard page

The next page asks us to specify the unit name of the GNAT project (not the file name), that is, the name within the gpr file.

Unlike the Eclipse project name, the GNAT project unit name must be a legal Ada identifier. The wizard will try to make a legal Ada name from the Eclipse project name, by substituting underscores for dashes for example. (If the Eclipse project name is already a legal Ada identifier that name is used unchanged.) In this case the wizard changed the single dash to an underscore so we have a legal Ada name for the project:

tutorial project unit name dialog

In the next page we enter the name of the Ada main subprogram – not the file name – and have the wizard generate the file containing that unit. We arbitrarily name the unit “hello” and have it generated as a program that prints “Hello World!” when executed.

new project wizard ada config page3

On the next page we then choose the locations for our source files and object files. The defaults will have all source files in the “src” folder, all object and “ali” files in the “obj” folder, and the executable also in the “obj” folder. We change the location of the executable so that it goes in a separate directory:

new project wizard ada config page

On the next page we choose the specific toolchain. We want the PowerPC-Elf toolchain for this demonstration, as shown below.

new project wizard ada config page5

Press Finish. The new project will be created and you will see it in the GNAT Project Explorer, like so:

created project in Project Explorer

In the view of the project (see the figure above), note the presence of the file named “gprbuild_demo.gpr”. This is the GNAT project file. This file may be edited but it must not be deleted.

Also note the file containing the main subprogram underneath the source folder (we expanded it to show the file). This file will have the name we specified, “hello.adb”, and will contain a procedure with that unit name:

tutorial main subprogram in editor

We will alter the content of the main subprogram momentarily.

1.12.2. Modifying the GNAT Project File

We must modify the GNAT project file created by the wizard. The original project file looks like this:

original project file from wizard

First, we need to tell the builder that we have more than Ada sources involved. This is accomplished via the Languages attribute. When this attribute is used and the “Multi-language Builder” preference is set to “Auto” the builder invokes gprbuild instead of gnatmake. This preference is located under the Ada “General” preferences category and is set to “Auto” by default.

Second, we need a linker script to link the executable because this is a bare-board application. Hence we must tell the linker how to find this script. The linker script is named “hi.ld” and we have imported it into the root of the project.

Therefore, we add the Languages attribute (line 3) and the Linker package for the sake of the script (lines 10 through 13) and the modified project file now looks like the following:

modified project file

1.12.3. The Source Files

As mentioned earlier we have sources in Ada, assembly, and C. You could have written these directly or imported them from the file system. We imported them in this case. We have expanded the src directory to show them in the project:

tutorial cross gprbuild sources

The assembly source file (“start.s”) is a short initialization sequence that has to be included in the final image.

The C function is a simple function just for illustration purposes.

1.12.4. Modifying the Main Subprogram Source File

We have altered the main subprogram so that it calls the C function. It also has a with-clause so that the implementation of the putchar routine is included in the executable. (The body of Putchar is referenced by the run-time library implementation of the GNAT.IO package. We call Putchar indirectly, via procedure Put_Line.)

tutorial cross gprbuild altered main

1.12.5. Building the Project

Now that the setup has completed we are ready to do the full build. In the GNAT Project Explorer, open the contextual menu and select “Build Project”.

project builder menu invocation

A successful build will appear in the Console view:

content of build console after successful build

Note the invocations of the compiler for the main subprogram (“hello.adb”), the assembly code routine (“start.s”), the C function (“hi.c”), and the other Ada file (“putchar.adb”).

1.12.6. Congratulations!

That’s it! You have created and built a project for an embedded computer using GPRbuild.