# Adadep.
The Ada Dependencies Analysis Tool

## Version 1.2

### Content:

- Copyright, etc.
- Installing Adadep
- Principle of operation
- Using Adadep
- Adadep and ASIS
- Troubleshooting
- Future of Adadep

Adadep is a tool for analysing dependencies. When an Ada unit references a package in a with clause, it means that something from this package is used in the unit. Adadep will tell you which elements from the package are really used by the unit. Since it is based on semantic analysis, it does not depend on how you use the elements (i.e. either using full named notation, or thanks to a use clause). It is another example of the nice things that can be made using ASIS.

Please send bug reports, remarks, notes, good ideas, etc. to J-P. Rosen .

## I. Copyright, etc.

This software is © Adalog, 2002. Adadep is free software; you can redistribute it and/or modify it under terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This unit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License distributed with this program; see file COPYING. If not, write to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

As a special exception, if other files instantiate generics from the units of this program, or if you link units provided with this program with other files to produce an executable, these units do not by themselves cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.

This program is offered with this very liberal license as a demonstration of Adalog's know-how; please do not remove the reference to Adalog in the header comment of each unit.

## II. Installing Adadep

This version uses ASIS-for-GNAT. As a consequence, you must have GNAT installed before you install Adadep (even if you downloaded an executable version). If you are using another compiler that provides an ASIS interface, you may recompile Adadep with this compiler. GNAT will not be necessary any more (but your compiler will, of course). See Adadep and ASIS.

If you downloaded an executable distribution of Adadep, please note that it has been compiled with GNAT 3.15p, and will not work with any other version of GNAT. If you have an older (or an ACT-supported) version of GNAT, either upgrade your GNAT to 3.15p (recommended for older version!), or recompile Adadep from the source distribution.

If you downloaded the source version of Adadep, you must make sure that ASIS is installed on your system, then simply gnatmake the file adadep.adb, including appropriate options to access the ASIS library.

Adadep needs no setup, no special rights. Simply copy the executable where you please.

This version has been tested under Windows/XP and Unix (SuSELinux 7.0 and above, Mandrake).

### II.1 Files list

File | Description | Note
adadep-guide.htm | This file. |
COPYING | The GNU General Public License file |
*.ad[bs] | Source files | In the source distribution
adadep | Linux executable file | In the Linux executable distribution
adadep.exe | Windows executable file | In the Windows executable distribution

## III. Principle of operation

Adadep reads one or more ada units, and produces an output file that lists, for each "withed" package, which elements are actually used. If several units are analyzed, the listing maybe separated for the dependencies of each unit, or alternatively be merged (i.e. there is one listing showing which element is used by any of the units). Given the following Ada units:

    package Pack is
       I : Integer;

       package Internal is
          V : Float;
       end Internal;
    end Pack;

    with Pack, Text_IO;
    use Pack, Text_IO;
    procedure Sample is
    begin
       I := 1;
       Internal.V := 3.0;
       Put_Line (Integer'Image (I + Integer(Internal.V)));
    end Sample;

A typical output of Adadep will look like this:

    SAMPLE (body) =>
    => from ADA.TEXT_IO
       PUT_LINE - A_Procedure_Declaration * 1
    => from PACK
       I - A_Variable_Declaration * 2
    => from PACK.INTERNAL
       V - A_Variable_Declaration * 2
    => from STANDARD
       INTEGER - An_Ordinary_Type_Declaration * 2

For each package, Adadep writes a line for each used element, a short description of what it is (ASIS users will recognize it as the Declaration_Kind), and the number of times it is referred to.

Note that the name given in the listing is always the "true" name of the element; in the case of renamings, it may be different from the name that appears in the program text.

## IV. Using adadep

Adadep is started by a command line of the form:

    adadep [-bdhmrsw] [-o <output-file>] [-p <project-file>] <unit-name>{+|-<unit-name>} | @<list-file> {<element-name>} [-- <ASIS-options>]

Options:

As usual, options can be grouped or provided separately (i.e. "-b -s" is the same as "-bs"). Options can appear at any place on the command line.

-b | process body of unit
-d | debug
-h | help. Print usage message and exit
-m | merge. Merge output of the various units
-o | specify the name of the output file. See below.
-p | use source directory indications from provided project file. See below.
-r | recursive. Process the unit and (recursively) all user units it depends on (including parent units if the unit is a child or a subunit). Predefined Ada units and units belonging to the compiler's run-time library are never processed.
-s | process specification of unit
-w | overwrite an existing output file

If the -h option is given, adadep just prints a brief usage summary and exits. If neither -s or -b is given, -sb is assumed (i.e. both the specification and body are processed).

If no "-o <output-file>" option is given, the result is simply written to the standard output. Otherwise, adadep will output the result of processing each unit to the given file. If the file already exists, the output is appended to it (unless there is a -w option, in which case it is overridden); this makes it possible to run adadep separately on several units, and keep the result in one file.

<unit-name> is the name of the ada unit to analyze; note that it is a unit name, not a file name: case is not significant, and there should be no extension! Of course, child units are allowed following normal Ada naming rules: "Parent.Child". Alternatively, you can give an "@" followed by the name of a file instead of a unit name. This file should contain a list of unit names, one on each line. All units whose names are given in the file will be processed. If a name in the file starts with "@", it will also be treated as an indirect file (i.e. the same process will be invoked recursively).

If one or more <element-name> is specified, output will be limited to those elements (including their sub-elements). For example, if you specify "Ada.Text_IO", then only Ada.Text_IO and elements declared within Ada.Text_IO will be listed. Note that you must specify elements as full names: if you want to include only references to the variable V declared in the (library) package Pack, you must give it as "pack.V". Of course, since we are talking Ada elements here, case is irrelevant.

Everything that appears after a "--" will be treated as an ASIS option, as described in the ASIS user manual. Normally, you don't have to care about this, except for the issue discussed below.

If the units that you are processing reference other units whose source is not in the same directory, Adadep needs to know how to access these units (as GNAT would). You can do this in two ways (not exclusive):

- You can specify a project file (the file with a ".adp" extension used by the Ada mode of Emacs) with the -p option. Adasubst will automatically consider all the directories mentionned in "src_dir" lines from the project file.
- you can include one or several "-I" options to reference other directories where sources can be found. The syntax is the same as the "-I" option for Gnat. Note that since "-I" is actually an ASIS option, it must appear after a "--".

## V. Adadep and ASIS

Adadep has been tested only with ASIS-for-gnat; however, the only (known) dependency is for the implementation-dependents parameters used to open an ASIS context. These parameters are defined as strings in the package Implementation_Options (file implementation_options.ads), so all you have to do if you want to port Adadep to another implementation is adjust these definitions. If you ever do so, please keep us informed by sending a note to rosen@adalog.fr.

## VI Troubleshooting

#### Message: Inconsistent tree file for ..., please remove .adt file

It is a consequence of the way ASIS works that tree files (with a .adt extension) are created as part of the process. Currently, these files are not erased by Adadep after execution. This speeds up execution if you run Adadep several times. However, if you change your source files, the trees are no more consistent with the sources. Simply remove the .adt files and rerun Adadep; new tree files will be created.

#### Adadep halts with an error

There are many subtile special cases when analysing Ada code, so it may happen that you find a context that we didn't think about. If you encounter a bug while using Adadep (generally an unhandled exception), Adadep will output a number of information. Please rerun it with the -d option (debug) and save the output to a file, then send this file together with the file you are processing to rosen@adalog.fr. We will do our best to fix it. Of course, you are welcome to try and fix it yourself; we made every attempt to make the source of Adadep quite readable, but be aware that you will need a good understanding of ASIS and Ada syntax to understand how it works.

## VII. Future of adadep

The structure of this programs allows it to be extended very easily. The notion of dependency extends far beyond "what do I use from this package". We intend to extend the functionnalities as we feel the need... or as users make suggestions!

Send good ideas, bug reports, suggestions of improvements to the program or to the documentation, etc. to rosen@adalog.fr (J-P. Rosen).

If you want commercial support for this product, or need any support or assistance for your Ada projects, please visit our Web site or send us a mail .