4. Hello World walk through

Creating a new module is best demonstrated by going through the classical and simple example ‘hello world’. This example will be refined as new extension possibilities are described later on in this document.

4.1. Declaring the module

A module is generally implemented in a separate source file, at this point an Ada package. The first thing that needs to be done is to create the specs of this package. Most of the time, a single function has to be exported, which is called Register_Module by convention. Therefore, we have to create a new directory to contain the module (we’ll call it hello_world), at the same level as other modules like the source editor.

Still by convention, the sources are put in a directory called src, and the object files are kept in a separate directory called obj:

mkdir hello_world
mkdir hello_world/src
mkdir hello_world/obj

In the source directory, we create the file hello_world.ads, which contains the declaration of the Register_Module subprogram:

with GPS.Kernel;
package Hello_World is
   procedure Register_Module
      (Kernel : access GPS.Kernel.Kernel_Handle_Record'Class);
end Hello_World;

Before going over the details of the implementation of Register_Module, we have to make sure that the rest of GPS knows about this module, and that we know how to compile it

4.2. Publicizing your module

Until GPS provides dynamic modules, you have to modify the main subprogram of GPS to make it aware of your module.

This is done by modifying the file gps.adb, and adding two statements in there: a with statement that imports hello_world.ads, and a call to Hello_World.Register_Module. See for instance how this is done for the keymanager module.

4.3. Compiling your module

However, after the addition of the two statements in gps.adb, the file hello_world.ads will not be found automatically by GPS. Therefore, you need to create a project file for your new module (we’ll call it hello_world.gpr), and add a dependency to it in the root project file of GPS (gps/gps.gpr), as is currently done for all other modules.

The project file hello_world.gpr is best created by copying the project file from any other module, for instance the aliases module (aliases/aliases.gpr), and changing the name of the project to Hello_World.

You must also create a set of two Makfiles, which are used to add files other than Ada, even if your module only uses Ada files. Once again, this is best done by copying the two Makefiles from the directory aliases, renaming them into Makefile and Makefile.hello_world, and replacing the strings aliases and ALIASES by resp. hello_world and HELLO_WORLD.

These steps will be made easier in the near future, but in any case are relatively straightforward, and only need to be done once per module. The resulting setup automatically takes into account all sources files that will be added later on to the module, either C or Ada, and compile them with the appropriate compiler.

You might also prefer in your first attempt at creating a new module to add your new files into the src directory of an existing module. In this case, you don’t have to create any of the project files or Makefile, nor to modify the gps.adb file.

Once the project file has been created, and a dependency added in gps.gpr, you might want to reload the GPS project in GPS, so that the editing of your sources can be done in an Ada-friendly context.

4.4. Registering the module

Back to the source files of your modules. We now need to create a body for the procedure Register_Module. The minimal thing this function has to do is indicate to the GPS kernel that a new module is being declared, and give it a name. If you only do that, there is no direct impact on the rest of GPS. However, as we will see during in this guide, having a specific Module_Id is mandatory for some of the advanced feature, so it is cleaner to always declare one from the start.

This is done by creating the file hello_world.adb, with the following contents:

with GPS.Kernel.Modules;  use GPS.Kernel, GPS.Kernel.Modules;

package Hello_World is
   procedure Register_Module
      (Kernel : access GPS.Kernel.Kernel_Handle_Record'Class)
   is
      Module : Module_ID;
   begin
      GPS.Kernel.Modules.Register_Module
         (Module, Kernel, Module_Name => "hello_world");
   end Register_Module;

end Hello_World;

At this point, the hello_world module is compilable, only it won’t do anything but be loaded in GPS.

The following sections will show how new features can be provided to the rest of GPS.