Addr2Line2Locations : Ada exceptions log and Addr2Line in GPS


« Addr2Line2locations », whose names comes after the one of « Addr2Line », is a utility for GPS ( an Ada language oriented IDE from AdaCore ), which provide you navigation in exceptions traceback and origin via the Locations pane of the GPS IDE.

Preliminary note about the GPS term as referred to here

If you was driven here after you've typed « GPS » in your favorite search engine, note, here the term stands for an Ada language oriented IDE from AdaCore . If you were seeking for some documentations about the Global Positioning System, you may be left a bit disappointed. But as you're there, you're still welcome to discover about what we are talking about here and to take part in the party.

The big lines and principle of « Addr2Line2Locations »

Addr2Line2Locations works on exception logs which may be displayed by an Ada application which was compiled and built with GNAT. These exception logs may contains call stack traceback addresses which are raw addresses in the memory space of the application which terminated on an un-handled exception.

Here are typical examples of such exception logs, to remind you something :

Execution terminated by unhandled exceptionException name: ASIS.EXCEPTIONS.ASIS_INAPPROPRIATE_ELEMENTMessage:
                  a4g-vcheck.adb:885Call stack traceback locations:0x494daa 0x4c620c
                  0x533f47 0x533f78 0x533e00 0x533e00 0x533e00 0x533e000x533e00 0x5338ed
                  0x536516 0x53218d 0x53245f 0x530f04 0x5383c3 0x4012350x401286 0x7c817075


Addresses shown in the first prototype, are mostly unusable as-is, and are typically passed to Addr2Line, part of the « GNU Binutils » suite  to turn application's memory space addresses into application's source line locations. Invoking Addr2Line for each addresses in a traceback list and getting each result returned by Addr2Line to go to the corresponding location in each source, is a tedious task ( may also be error prone ). It is even more tedious if it ever has to be repeated multiple times.

The GPS IDE embeds a standard pane, called the Locations pane, which is most of time used to navigate through GPRBuild, GNATMake or « AdaControl »  ( a utility you're supposed to know about ) warning and error messages. This would be nice if an application could provide a similar and handy navigation in exception tracebacks. That is the purpose of Addr2Line2Locations.

Side note : if an exception log does not contain traceback addresses, Addr2Line2Locations will still do a bit of useful job for you : if it found the location of the statement which raised the exception, it will give it to you in the Locations pane as well. The statement which raise an exception is indeed not part of the traceback list, and is a data kept apart. The traceback list contains addresses of subprogram calls, and an Ada Raise statement is not a subprogram call. The location of the statement which raised the exception, may not be determinate if the exception was raised with a custom message ; i.e. a Raise EXCEPTION_NAME with" Custom Message" like statement, as permitted by Ada ARM 2005 - 11.3 2/2 .

License agreements

If now you known what's this, you are interested in this application, its time to know about the license : Addr2Line2Locations may be used under the terms of the Two Clause BSD License, alias the Simplified BSD license, which grant you the right to use and distribute this application for commercial purpose or not, modified or not ( just think to point about it so, there should not be any confusion in such circumstance ), providing you keep the copyright notice, license, and contact of all previous authors ( if you use a version already modified by others ) informations included in the source file. More about this license : Overview of the Two-Clause or Simplified BSD License 

How it works ( from the user's point of view )

Addr2Line2Locations will be presented to you, GPS user, as a new menu entry in the GPS Tools menu. Running the utility will lead you to a dialog box requesting you to enter data required to computed the latter introduced browsable entries in the Locations pane. Conveniently for you, you are not required to separate and format any traceback addresses list, this will be done for you. You are expected, if required ( see later ) to paste the end of the output of any application which raised an exception and, if required ( see later ) to enter the name of the executable of this application. Then validate, and wait for entries to be displayed in the Locations pane, unless you are informed by a message box, that no location data could be retrieve from the exception log.

The « Addr2Line2Locations » dialog with entries filled

The Addr2Line2Locations dialog with entries filled

To ease and speed use, the Addr2Line2Locations dialog fields will be filled automatically as much as possible. The exception log text will be filled after any GPS console which may be active at the time you activated the Addr2Line2Locations command. So, it is able to work as context sensitive command and it is thus suggested you first click on any console containing the exception log, before you requested the utility. As a consequence, this may be more convenient if you run any application using a GPS console or redirecting its output to a GPS console. This works nice as well with tools which redirect any runtime error messages to a console, as AdaControl and ASISEyes does.

The dialog which
            was automatically initialized after the content of the console at
            the left

The dialog which was automatically initialized after the content of the console at the left

The executable name text will be automatically filled, if possible, after the current project properties. If your current project is designed to build multiple executables, then you will be provided a list to choose among. The field will any way stay editable, so that if the executable name does not belong to the list, you will be able to enter it manually.

The executable
            name input, automatically filled from project

The executable name input, automatically filled from project

Note : if the application does not belong to your project current directory, you should give it a full name, i.e. directory and executable file name. The name must always be given an extension if applicable ( as an example, on Windows or UNIX-like platforms, among others, not to be exhaustive ).

How it works ( from the developer's point of view )

First of all, as a developer, if you plan to make use of the Addr2Line2Locations module, you are supposed to be aware of the user’s point of view, which you should have read as well.

Addr2Line2Locations is a Python module, which you may use without requesting the user to manually trigger the Addr2Line2Locations tool from menu. The invok_addr2line method is provided for use in your applications, and is defined as :

def invok_addr2line (executable_name = None, exception_log = None):#
                  … Implementation


You may use it with error output from any application as the exception_log parameter. Both of its parameters are optional. When one or both is None, then the dialog presented in the user's point of view will be popped-up. The same if it appears exception_log does not contain the requested informations. For more details, you may refer to the module documentation or to the documentation of each method defined in the module ; or rely to source comments as a last resort, may also send an e-mail to the contact indicated in the module's copyright notice.

You may possibly use any of the other methods defined in this module, providing some may not be guaranteed to be persistent in eventually coming updates. If you want to rely on a method else than invok_addr2line, tell about it via the contact provided in the source module.

Getting « Addr2Line2Locations »

Depending on the standard archiver on your platform, you may get it as either a ZIP or a TAR.GZ archive, actually, version 1, revision 2 V1R2 ) :

Installing Addr2Line2Locations

Copy the Python file in the « share/gps/plug-ins » subdirectory of your GPS installation. This will install Addr2Line2Locations for all users on your machine. For a single or per user installation, copy the Python file in the « .gps/plug-ins » subdirectory of the user profile of each users you want to install this for ( same for both Windows and UNIX-like ).