GNAT GPL User's Guide: Other Utility Programs

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 30. Other Utility Programs

This chapter discusses some other utility programs available in the Ada environment.

> 30.1 Using Other Utility Programs with GNAT |  |
> 30.2 The External Symbol Naming Scheme of GNAT |  |
> 30.3 Converting Ada Files to HTML with `gnathtml` |  |
> 30.4 Installing `gnathtml` |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 30.1 Using Other Utility Programs with GNAT

The object files generated by GNAT are in standard system format and in particular the debugging information uses this format. This means programs generated by GNAT can be used with existing utilities that depend on these formats.

In general, any utility program that works with C will also often work with Ada programs generated by GNAT. This includes software utilities such as gprof (a profiling program), `gdb` (the FSF debugger), and utilities such as Purify.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 30.2 The External Symbol Naming Scheme of GNAT

In order to interpret the output from GNAT, when using tools that are originally intended for use with other languages, it is useful to understand the conventions used to generate link names from the Ada entity names.

All link names are in all lowercase letters. With the exception of library procedure names, the mechanism used is simply to use the full expanded Ada name with dots replaced by double underscores. For example, suppose we have the following package spec:

    package QRS is
       MN : Integer;
    end QRS;

The variable `MN` has a full expanded Ada name of `QRS.MN`, so the corresponding link name is `qrs__mn`. Of course if a `pragma Export` is used this may be overridden:

    package Exports is
       Var1 : Integer;
       pragma Export (Var1, C, External_Name => "var1_name");
       Var2 : Integer;
       pragma Export (Var2, C, Link_Name => "var2_link_name");
    end Exports;

In this case, the link name for Var1 is whatever link name the C compiler would assign for the C function var1_name. This typically would be either var1_name or _var1_name, depending on operating system conventions, but other possibilities exist. The link name for Var2 is var2_link_name, and this is not operating system dependent.

One exception occurs for library level procedures. A potential ambiguity arises between the required name `_main` for the C main program, and the name we would otherwise assign to an Ada library level procedure called `Main` (which might well not be the main program).

To avoid this ambiguity, we attach the prefix `_ada_` to such names. So if we have a library level procedure such as

    procedure Hello (S : String);

the external name of this procedure will be _ada_hello.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 30.3 Converting Ada Files to HTML with `gnathtml`

This `Perl` script allows Ada source files to be browsed using standard Web browsers. For installation procedure, see the section See section 30.4 Installing `gnathtml`.

Ada reserved keywords are highlighted in a bold font and Ada comments in a blue font. Unless your program was compiled with the gcc ``-gnatx'` switch to suppress the generation of cross-referencing information, user defined variables and types will appear in a different color; you will be able to click on any identifier and go to its declaration.

The command line is as follow:

    $ perl gnathtml.pl [switches] ada-files

You can pass it as many Ada files as you want. `gnathtml` will generate an html file for every ada file, and a global file called ``index.htm'`. This file is an index of every identifier defined in the files.

The available switches are the following ones:

``-83'`
  Only the Ada 83 subset of keywords will be highlighted.

``-cc color'`
  This option allows you to change the color used for comments. The default value is green. The color argument can be any name accepted by html.

``-d'`
  If the Ada files depend on some other files (for instance through `with` clauses, the latter files will also be converted to html. Only the files in the user project will be converted to html, not the files in the run-time library itself.

``-D'`
  This command is the same as ``-d'` above, but `gnathtml` will also look for files in the run-time library, and generate html files for them.

``-ext extension'`
  This option allows you to change the extension of the generated HTML files. If you do not specify an extension, it will default to ``htm'`.

``-f'`
  By default, gnathtml will generate html links only for global entities ('with'ed units, global variables and types,...). If you specify ``-f'` on the command line, then links will be generated for local entities too.

``-l number'`
  If this switch is provided and number is not 0, then `gnathtml` will number the html files every number line.

``-I dir'`
  Specify a directory to search for library files (``.ALI'` files) and source files. You can provide several -I switches on the command line, and the directories will be parsed in the order of the command line.

``-o dir'`
  Specify the output directory for html files. By default, gnathtml will saved the generated html files in a subdirectory named ``html/'`.

``-p file'`
  If you are using Emacs and the most recent Emacs Ada mode, which provides a full Integrated Development Environment for compiling, checking, running and debugging applications, you may use ``.gpr'` files to give the directories where Emacs can find sources and object files.

  Using this switch, you can tell gnathtml to use these files. This allows you to get an html version of your application, even if it is spread over multiple directories.

``-sc color'`
  This switch allows you to change the color used for symbol definitions. The default value is red. The color argument can be any name accepted by html.

``-t file'`
  This switch provides the name of a file. This file contains a list of file names to be converted, and the effect is exactly as though they had appeared explicitly on the command line. This is the recommended way to work around the command line length limit on some systems.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 30.4 Installing `gnathtml`

`Perl` needs to be installed on your machine to run this script. `Perl` is freely available for almost every architecture and Operating System via the Internet.

On Unix systems, you may want to modify the first line of the script `gnathtml`, to explicitly tell the Operating system where Perl is. The syntax of this line is:

    #!full_path_name_to_perl

Alternatively, you may run the script using the following command line:

    $ perl gnathtml.pl [switches] files

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html