5. GNAT Utility Programs#
This chapter describes a number of utility programs:
Other GNAT utilities are described elsewhere in this manual:
5.1. The File Cleanup Utility gnatclean
#
gnatclean
is a tool that allows the deletion of files produced by the
compiler, binder and linker, including ALI files, object files, tree files,
expanded source files, library files, interface copy source files, binder
generated files and executable files.
5.1.1. Running gnatclean
#
The gnatclean
command has the form:
$ gnatclean switches names
where names
is a list of source file names. Suffixes .ads
and
adb
may be omitted. If a project file is specified using switch
-P
, then names
may be completely omitted.
In normal mode, gnatclean
delete the files produced by the compiler and,
if switch -c
is not specified, by the binder and
the linker. In informative-only mode, specified by switch
-n
, the list of files that would have been deleted in
normal mode is listed, but no file is actually deleted.
5.1.2. Switches for gnatclean
#
gnatclean
recognizes the following switches:
--version
Display copyright and version, then exit disregarding all other options.
--help
If
--version
was not used, display usage, then exit disregarding all other options.--subdirs=subdir
Actual object directory of each project file is the subdirectory subdir of the object directory specified or defaulted in the project file.
--unchecked-shared-lib-imports
By default, shared library projects are not allowed to import static library projects. When this switch is used on the command line, this restriction is relaxed.
-c
Only attempt to delete the files produced by the compiler, not those produced by the binder or the linker. The files that are not to be deleted are library files, interface copy files, binder generated files and executable files.
-D dir
Indicate that ALI and object files should normally be found in directory
dir
.
-F
When using project files, if some errors or warnings are detected during parsing and verbose mode is not in effect (no use of switch -v), then error lines start with the full path name of the project file, rather than its simple file name.
-h
Output a message explaining the usage of
gnatclean
.
-n
Informative-only mode. Do not delete any files. Output the list of the files that would have been deleted if this switch was not specified.
-Pproject
Use project file
project
. Only one such switch can be used. When cleaning a project file, the files produced by the compilation of the immediate sources or inherited sources of the project files are to be deleted. This is not depending on the presence or not of executable names on the command line.
-q
Quiet output. If there are no errors, do not output anything, except in verbose mode (switch -v) or in informative-only mode (switch -n).
-r
When a project file is specified (using switch -P), clean all imported and extended project files, recursively. If this switch is not specified, only the files related to the main project file are to be deleted. This switch has no effect if no project file is specified.
-v
Verbose mode.
-vPx
Indicates the verbosity of the parsing of GNAT project files. Switches Related to Project Files.
-Xname=value
Indicates that external variable
name
has the valuevalue
. The Project Manager will use this value for occurrences ofexternal(name)
when parsing the project file. See Switches Related to Project Files.
-aOdir
When searching for ALI and object files, look in directory
dir
.
-Idir
Equivalent to
-aOdir
.
-I-
Do not look for ALI or object files in the directory where
gnatclean
was invoked.
5.2. 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.
5.2.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 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 option
-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.
5.2.2. Switches for gnatls
#
gnatls
recognizes the following switches:
--version
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 filefile
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 (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 (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.
5.2.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