GNAT GPL User's Guide: The GNAT Library Browser gnatls

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

# 19. The GNAT Library Browser `gnatls`

`gnatls` is a tool that outputs information about compiled units. It gives the relationship between objects, unit names and source files. It can also be used to check the source dependencies of a unit as well as various characteristics.

Note: to invoke `gnatls` with a project file, use the `gnat` driver (see 12.2 The GNAT Driver and Project Files).

> 19.1 Running `gnatls` |  |
> 19.2 Switches for `gnatls` |  |
> 19.3 Example of `gnatls` Usage |  |

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

## 19.1 Running `gnatls`

The `gnatls` command has the form

    $ gnatls switches object_or_ali_file

The main argument is the list of object or ``ali'` files (see section 2.8 The Ada Library Information Files) for which information is requested.

In normal mode, without additional option, `gnatls` produces a four-column listing. Each line represents information for a specific object. The first column gives the full path of the object, the second column gives the name of the principal unit in this object, the third column gives the status of the source and the fourth column gives the full path of the source representing this unit. Here is a simple example of use:

    $ gnatls *.o
    ./demo1.o            demo1            DIF demo1.adb
    ./demo2.o            demo2             OK demo2.adb
    ./hello.o            h1                OK hello.adb
    ./instr-child.o      instr.child      MOK instr-child.adb
    ./instr.o            instr             OK instr.adb
    ./tef.o              tef              DIF tef.adb
    ./text_io_example.o  text_io_example   OK text_io_example.adb
    ./tgef.o             tgef             DIF tgef.adb

The first line can be interpreted as follows: the main unit which is contained in object file ``demo1.o'` is demo1, whose main source is in ``demo1.adb'`. Furthermore, the version of the source used for the compilation of demo1 has been modified (DIF). Each source file has a status qualifier which can be:

`OK (unchanged)`
  The version of the source file used for the compilation of the specified unit corresponds exactly to the actual source file.

`MOK (slightly modified)`
  The version of the source file used for the compilation of the specified unit differs from the actual source file but not enough to require recompilation. If you use gnatmake with the qualifier ``-m (minimal recompilation)'`, a file marked MOK will not be recompiled.

`DIF (modified)`
  No version of the source found on the path corresponds to the source used to build this object.

`??? (file not found)`
  No source file was found for this unit.

`HID (hidden, unchanged version not first on PATH)`
  The version of the source that corresponds exactly to the source used for compilation has been found on the path but it is hidden by another version of the same source that has been modified.

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

## 19.2 Switches for `gnatls`

`gnatls` recognizes the following switches:

Display Copyright and version, then exit disregarding all other options.
``--help'`
  If ``--version'` was not used, display usage, then exit disregarding all other options.

``-a'`
  Consider all units, including those of the predefined Ada library. Especially useful with ``-d'`.

``-d'`
  List sources from which specified units depend on.

``-h'`
  Output the list of options.

``-o'`
  Only output information about object files.

``-s'`
  Only output information about source files.

``-u'`
  Only output information about compilation units.

``-files=file'`
  Take as arguments the files listed in text file file. Text file file may contain empty lines that are ignored. Each nonempty line should contain the name of an existing file. Several such switches may be specified simultaneously.

``-aOdir'`
``-aIdir'`
``-Idir'`
``-I-'`
``-nostdinc'`
  Source path manipulation. Same meaning as the equivalent `gnatmake` flags (see section 6.2 Switches for `gnatmake`).

``-aPdir'`
  Add dir at the beginning of the project search dir.

``--RTS=rts-path'`
  Specifies the default location of the runtime library. Same meaning as the equivalent `gnatmake` flag (see section 6.2 Switches for `gnatmake`).

``-v'`
  Verbose mode. Output the complete source, object and project paths. Do not use the default column layout but instead use long format giving as much as information possible on each requested units, including special characteristics such as:

  `Preelaborable`
    The unit is preelaborable in the Ada sense.

  `No_Elab_Code`
    No elaboration code has been produced by the compiler for this unit.

  `Pure`
    The unit is pure in the Ada sense.

  `Elaborate_Body`
    The unit contains a pragma Elaborate_Body.

  `Remote_Types`
    The unit contains a pragma Remote_Types.

  `Shared_Passive`
    The unit contains a pragma Shared_Passive.

  `Predefined`
    This unit is part of the predefined environment and cannot be modified by the user.

  `Remote_Call_Interface`
    The unit contains a pragma Remote_Call_Interface.

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

## 19.3 Example of `gnatls` Usage

Example of using the verbose switch. Note how the source and object paths are affected by the -I switch.

    $ gnatls -v -I.. demo1.o

    GNATLS 5.03w (20041123-34)
    Copyright 1997-2004 Free Software Foundation, Inc.

    Source Search Path:
       <Current_Directory>
       ../
       /home/comar/local/adainclude/

    Object Search Path:
       <Current_Directory>
       ../
       /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/

    Project Search Path:
       <Current_Directory>
       /home/comar/local/lib/gnat/

    ./demo1.o
       Unit =>
         Name   => demo1
         Kind   => subprogram body
         Flags  => No_Elab_Code
         Source => demo1.adb    modified

The following is an example of use of the dependency list. Note the use of the -s switch which gives a straight list of source files. This can be useful for building specialized scripts.

    $ gnatls -d demo2.o
    ./demo2.o   demo2        OK demo2.adb
                             OK gen_list.ads
                             OK gen_list.adb
                             OK instr.ads
                             OK instr-child.ads

    $ gnatls -d -s -a demo1.o
    demo1.adb
    /home/comar/local/adainclude/ada.ads
    /home/comar/local/adainclude/a-finali.ads
    /home/comar/local/adainclude/a-filico.ads
    /home/comar/local/adainclude/a-stream.ads
    /home/comar/local/adainclude/a-tags.ads
    gen_list.ads
    gen_list.adb
    /home/comar/local/adainclude/gnat.ads
    /home/comar/local/adainclude/g-io.ads
    instr.ads
    /home/comar/local/adainclude/system.ads
    /home/comar/local/adainclude/s-exctab.ads
    /home/comar/local/adainclude/s-finimp.ads
    /home/comar/local/adainclude/s-finroo.ads
    /home/comar/local/adainclude/s-secsta.ads
    /home/comar/local/adainclude/s-stalib.ads
    /home/comar/local/adainclude/s-stoele.ads
    /home/comar/local/adainclude/s-stratt.ads
    /home/comar/local/adainclude/s-tasoli.ads
    /home/comar/local/adainclude/s-unstyp.ads
    /home/comar/local/adainclude/unchconv.ads

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

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