************************
Hello World walk through
************************

.. highlight:: ada

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.

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 :file:`hello_world`), at
the same level as other modules like the source editor.

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

  mkdir hello_world
  mkdir hello_world/src
  mkdir hello_world/obj
  

In the source directory, we create the file :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

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 :file:`gps.adb`, and adding two statements
in there: a `with` statement that imports :file:`hello_world`.ads, and
a call to `Hello_World.Register_Module`. See for instance how this is
done for the keymanager module.

Compiling your module
=====================

However, after the addition of the two statements in :file:`gps.adb`, the file
: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
:file:`hello_world.gpr`), and add a dependency to it in the root project file
of GPS (:file:`gps/gps.gpr`), as is currently done for all other modules.

The project file :file:`hello_world.gpr` is best created by copying the
project file from any other module, for instance the aliases module
(:file:`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 :file:`aliases`, renaming them into :file:`Makefile` and
:file:`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 :file:`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 :file:`gps.adb` file.

Once the project file has been created, and a dependency added in
:file:`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.

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 :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.