Managing Ada projects with Eclipse

Install Eclipse:

The first thing to do is to install Eclipse.

Download the installer from the Eclipse WEB site. The file is named eclipse-inst-jre-win64.exe. Run the installer and select Eclipse IDE for Embedded C/C++ Developers

I kept the default installation path : C:\eclipse\embedcpp-2023-06.

At the time of writing, the Eclipse installer has a bug [1] that causes an internal Eclipse file not to be installed. As this file is necessary for what we want to do, we need to find a way of retrieving it.

But first, let's check whether the bug is present in the version of Eclipse we've just installed. To do this, launch Eclipse and display the preferences dialog box (Window/Preferences).

If, as in the image above, the Language Configuration submenu is missing, then we need to install the TextMate plugin manually. To do this:

• Go in the menu Help / Install New Software...
• Click on Add...

• In the field Name, enter TextMate
• In the field Location, enter https://download.eclipse.org/tm4e/snapshots/
• Validate by clicking on the Add button.

• Select Dependencies, Samples, Sources, TextMate [2]
• Click on the Next... button
• Click on the Next... button
• Select I accept the terms of the license agreement
• Click on the Finish button

The preferences dialog box should now contain the Language Configuration sub-menu.

Last, to workaround a Eclipse bug we need to create the file .pkglist in the C:\Users\xxx\ folder where xxx is the current user name (Windows user name).

If this file already exists, don't touch it else just create it (void content).

Get Language Server files:

To do what we want we also need some files from the Ada Language Server project.

We could compile this project ourselves with the corresponding Alire crate or simply get the binary from the github project releases.

Keep things simple get the binaries. Download the last Windows version. At the time of writing, it is version 23.0.21 : als-23.0.21-Windows_amd64.zip. The archive contains a unique executable file, ada_language_server.exe, which we will copy in a dedicated folder. On my PC, I've chosen Z:\ada\language_server\.

We also need other files. Download the project sources archive.

In this archive, go to ada_language_server-master\integration\vscode\ada\ . Copy the following files in the same folder as ada_language_server.exe (the tree structure is not reproduced) :

• language-configuration.json
• gpr-language-configuration.json
• syntaxes\ada.tmLanguage.json
• syntaxes\gpr.tmLanguage.json
• syntaxes\ali.tmLanguage.json

A few modifications are required.

In the file ali.tmLanguage.json, replace the folloxing line...

"name": "ALI",

...with these lines :

 "name": "ali",
 "comment": "Ada ali grammar file",
 "scopeName": "source.ali",
 "fileTypes": [
     "ali"
 ],

In the file gpr.tmLanguage.json, after the following line ...

"name": "gpr",

...add these lines :

 "comment": "Ada project grammar file",
 "scopeName": "source.gpr",
 "fileTypes": [
     "gpr"
 ],

Now, we have everything we need to configure Eclipse.

Eclipse configuration:

Part of the configuration is done at the workspace level. Another part is done at the project level.

Let's start with the workspace configuration. For this we need to create a test folder. In my case : Z:\ada\eclipse-test\ . Start Eclipse and open a workspace in the folder we've just created.

We can close the Welcome window.

Content Types :

Let's associate file extensions to Content types.

Open the preferences dialog box (Window/Preferences menu) and go to General/Content Types menu. We need to add children to the Text entry :

• Click on Text
• Click on Add Child...
• Enter Ada and Validate
• In the File associations area, add *.adb et *.ads
• In the Default encoding area, enter utf-8
• Do the same with Ada_ALI (*.ali)
• Do the same with Ada_GPR (*.gpr)
• Click Apply

Note : It is important that the new entries are children of Text.

File Associations :

We will now associate file extensions with editor types. For this, open the preferences dialog box (Window/Preferences menu) and go to General/Editors/File Associations menu.

• Click on the Add... button
• Enter *.ads and validate
• In the Associated editors area, click on Generic Text Editor
• Click on the Default button
• Do the same with *.adb
• Do the same with *.gpr
• Do the same with *.ali
• Click on Apply and Close

Language Server :

Let's start by creating a Language Server launch configuration. Open the external tool dialog box : Run/External Tools/External Tools Configurations menu.

• Create a new launch configuration by clicking on the New launch configuration icon.

• In the Main tab:

  • In the Name text field enter Language Server
  • In the Location text field enter Z:\ada\language_server\ada_language_server.exe
  • In the Working Directory text field enter ${project_loc}

• In the Build tab:

  • Uncheck Build before launch

• In the Common tab:

  • In the Standard Input and Output area

    • Check Allocate console (necessary for input)

• In the Environment tab:

  • Click on Add...

    • In the Name text field enter PATH
    • In the Value text field enter C:/Program Files/Alirebin;${env_var:PATH}

• Click on the Apply button
• Click on the Close button

We now have to associate some Content-type to the language server we've just configured. Open the preferences dialog box (Window/Preferences menu) and go to Language Servers menu.

• Click on the Add... button
• In the Associate content-type... area select Text/Ada
• In the ... with Language Server Launch Configuration area select Program/Language Server
• Validate by clicking on the OK button
• Do the same with Text/Ada_ALI
• Do the same with Text/Ada_GPR
• Click on the "Apply" button

TextMate :

TextMate is plugin managing the code tokenization which allows to add syntax coloring, ctrl+click management, auto-completion...

Open the preferences dialog box (Window/Preferences menu) and go to the TextMate/Grammar menu.

• Click on the Add... button
• Click on the Browse Filesystem... button
• Select *.json at bottom right of dialog box
• Go to the folder where language server files are and select ada.tmLanguage.json
• Click on the open button
• Click on the Finish button
• Do the same with ali.tmLanguage.json
• Do the same with gpr.tmLanguage.json
• Click on the Apply button

Go to the TextMate/Language Configuration menu

• Click on the New button
• Click on the Browser Filesystem... button
• Select language-configuration.json
• Click on the Open button
• In the Content Type area select Text/Ada
• Click on the Finish button
• Do the same with gpr-language-configuration.json (Text/Ada_GPR)
• Click on the Apply button

Error parser :

Each compileur outputs errors/warnings its own way. We're going to make Eclipse understand the output format of the GNAT compiler.

In the preferences dialog box go to the C/C++/Build/Settings Menu

• In the Error Parsers tab click on the Add button
• Enter GNAT and validate
• In the Error Parser Options area click on the Add button

• A line is added to the list

  • In the Severity column select Error
  • In the Pattern column enter (.+):(\d+):(\d+): (error): (.*)
  • In the File column enter $1
  • In the Line column enter $2
  • In the Description column enter $5 (col $3)
  • Keep the Consume column void (do not select No)

• In the Error Parser Options area click again on the Add button

• A line is added to the list

  • In the Severity column select Warning
  • In the Pattern column enter (.+):(\d+):(\d+): (warning): (.*)
  • In the File column enter $1
  • In the Line column enter $2
  • In the Description column enter $5 (col $3)
  • Keep the Consume column void (do not select No)

• In the Error Parser Options area click again on the Add button

• A line is added to the list

  • In the Severity column select Info
  • In the Pattern column enter (.+):(\d+):(\d+): (\(style\)) (.*)
  • In the File column enter $1
  • In the Line column enter $2
  • In the Description column enter $5 (col $3)
  • Keep the Consume column void (do not select No)

• In the Error Parsers tab unselect everything except GNAT
• Click on the Apply And Close button

Projet creation:

The project creation needs two steps :

• Create a Alire project
• Create a Eclipse project.

We will first create tools to ease the acces to a Alire terminal [3].

1 - First tool: a Alire terminal at the workspace level. It will let us create Alire project.

• Open the external tool dialog box : Run/External Tools/External Tools Configurations menu
• Create a new launch configuration called Alire - Manage Projects

• In the Main tab :

  • In the Location text field enter C:WindowsSystem32WindowsPowerShellv1.0powershell.exe
  • In the Working Directory text field enter ${workspace_loc}
  • In the Arguments text field enter -NoExit -Command clear-host

• In the Build tab :

  • Uncheck Build before launch

• In the Environment tab click on the Add... button

  • In the Name text field enter PATH
  • In the Value text field enter ${env_var:PATH};C:/Program Files/Alire\bin
  • Validate

• In the Common tab :

  • In the Display in Favorite Menu area check External Tools
  • Check Allocate console (necessary for input)
  • Click on the Apply button.

2 - Second tool: a Alire terminal at the projet level. It will let us manage Alire projects.

• Duplicate the previous configuration and name it Alire - Manage Current Project
• In the Working Directory text field enter ${project_loc}
• Click on the Apply button

3 - Third tool: a shortcut to create a Alire project.

• Duplicate the configuration Alire - Manage Projects and name it Alire - Create Binary Project

• In the Main tab :

  • In the Location text field enter C:\Program Files\Alire\bin\alr.exe
  • In the Arguments text field enter init --bin ${string_prompt}

• Click on the Apply button
• Click on the Close button

On can also add a configuration to create a Alire library. For this duplicate the Alire - Create Binary Project configuration and replace --bin with --lib in the Arguments text field.

Creation of the first project (finally):

We wil start by creating a Alire project:

• Click on the arrow on the right of the External Tools icon
• Click on Alire - Create Binary Project
• Enter hello
• Validate

A message is displayed in the console : Success: hello initialized successfully.

Now, we will create a Eclipse project :

• In the File menu select New then C/C++ Project
• Select C Managed Build and click on the Next button
• In the Project name test field enter hello (the name must be the same as the one used when creating a Alire project)
• In the Project type area select Empty Project
• In the Toolchains area select Cross GCC
• Click on the Next button
• Click on the Next button
• Click on the Finish button

The project tree is displayed in the Project Explorer panel.

Project configuration:

To be able to compile and run our project, we need to configure it first..

For this, select the project by clicking on its icon and open the Project/Properties menu.

• Select C/C++ Build

• In the Builder Settings tab:

  • Uncheck Use default build command
  • In the Build Command text field enter C:\Program Files\Alire\bin\alr.exe
  • Uncheck Generate Makefiles automatically
  • In the Build directory text field suppress everything after the } character

• In the Behavior tab:

  • Check Use custom build arguments
  • Keep the Build arguments text field empty
  • In the Build text field enter build
  • In the Clean text field enter clean

Let's configure the Error Parser.

• Select C/C++ Build / Settings

• In the Error Parsers tab:

  • Check GNAT
  • Uncheck other parsers

Note : Everything we've done so far is for the default debug configuration. We can do the same for the release configuration.

Last step, create a launch configuration.

• Select Run/Debug Settings
• Click on the New... button
• Select C/C++ Application and validate

• In the Main tab:

  • In the C/C++ Application text field enter C:\Program Files\Alire\bin\alr.exe
  • Check Disable auto build

• In the Arguments tab:

  • In the Program Arguments text field enter run

• Click on the OK button
• Click on the Apply & Close button

We have to modify the hello.gpr file for the compiler to output absolute file names. For this we have to add the*-gnatef* option to the compilation parameters. like this :

package Compiler is
   for Default_Switches ("Ada") use Hello_Config.Ada_Compiler_Switches & ("-gnatef");

We can now edit / compile / execute our code. A double click on hello.adb opens an editor with the file content. We can immediately see the syntax coloration.

Hovering hello (the procedure name) shows the procedure définition.

Hitting CTRL+B triggers the project compilation. On can see the compiler output in the console.

Let us modify the code to generate errors and warnings when compiling :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

with Ada.Text_IO; use Ada.Text_IO;

procedure Hello is
   good_init : Natural := 0;
   bad_init  : Natural := -1;
begin
   -- Missing space
   Put ("Hello world");
   bad_assignment := 1;
end Hello;

Note that automatic completion works. CTRL+Click on an "object " also works.

The compilation output is like this :

Interresting. One can see the errors, warnings and style errors. However, one can not click on them. To solve this problem, go to the Problems tab. In this tab, one can click on the list elements to directly go to the offending line of code.

In the source file, the offending lines are annotated.

To run the compiled program, we need to:

• Click on the arrow at the right of the icon to open the menu.
• Click on Run Configurations...
• Select Hello Debug then click on Run

We can pass arguments to the executed program with the Arguments tab.

Next time we execute the program, we can click on the icon directly.

Configuration copy:

We now have a functional configuration that allows Ada code to be edited and executed. But it's very tedious to setup every Eclipse workspace and every project used to manage Ada code.

One way of partially solving the problem is to use Eclipse's configuration import/export feature. Go to the preferences dialog box (Window/Preferences): On the bottom left are 2 icons. One for export and one for import.

Project configuration can't be exported/imported.

Conclusion :

• Complex set-up
• Every time Eclipse or one of its associated tools is updated, problems can appear. Or disappear.
• In the editor, double quotes highlighting (used for character strings) doesn't work properly.
• The integrated language server client has flaws (double instantiation, blocking...).

The appeal of this configuration lies in its integrated multi-project management (not just Ada) and extensive list of plug-ins, a high-performance source comparator...

Everyone can see for themselves the usefulness of this solution by trying it out. Provided you have the courage, of course ;)

Note : Translated with the help of DeepL.