------------------------------------------------------------------------------
--                                                                          --
--                              GNAT DOCUMENTS                              --
--                                I N T R O                                 --
--                                                                          --
--                                                                          --
--                                                                          -- 
--                                                                          --
--           Copyright (c) 1992,1993,1994 NYU, All Rights Reserved          --
--                                                                          --
-- GNAT 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.  GNAT is distributed  in the hope  that it will be useful,  but --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANT- --
-- ABILITY 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 along with GNAT;  see file COPYING. If not, write --
-- to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. --
--                                                                          --
------------------------------------------------------------------------------

Contents.
---------
   Running GNAT.
   A small example.
   Gnatbl.
   Using the binder.
   Using gcc to compile.
   Using gcc for syntax checking.
   Using gcc for semantics checking.
   Search Paths and the Run Time Library (RTL).
   Options.  
   Constraint Checking and Pragma Suppress
   Order of Compilation Issues.
   File Name Rules.
   Compiling Files With Several Compilation Units.
   Cross Reference Tool.
   Implementation of Intrinsic Functions.
   Getting Internal Debugging Information.
   When GNAT crashes.
   Using gdb.
   Features supported/unsupported.
   Files.
   Copyright considerations.
   How to get in touch with us.
   Schedule.
   A short gnat paper.
   The GNAT development team.
------------------------------------------------------------------------------ 

Running GNAT.
-------------
Three steps are needed to create an executable file from an Ada source file:
it must first be compiled, it then must go through the gnat binder, and then
all appropriate object files it needs are then linked together to produce an
executable.  A tool has been provided to combine the last 2 steps into one
command.

A small example.
----------------

The file hello.adb contains the source of our modest version of the
"Hello World" program.  Other components of this program are contained
in the GNAT Runtime Library (RTL).  You needn't mention the files
containing these other components but you can find the sources (io.ads,
io.adb, and a-cio.c) in the RTL source directory (described below).

The file hello.adb can be found in the current distribution in the examples
directory.  Here are the commands for building and running it (Since this
documentation is for systems running Unix and also for those running
IBM OS/2 2.x, in places where the instructions differ a prefix "Unix:" or
"OS/2:" indicates what is relevant for each system):

            gcc -c hello.adb
      Unix: gnatbl -o hello hello.ali
      OS/2: gnatbl -o hello.exe hello.ali

create the executable called "hello" or "hello.exe" in your current directory.
Typing

      hello

will allow you to verify that the system is alive and willing to enter into 
a primitive dialogue.

The gcc switch -c indicates that we only want to compile, not link. The gnatbl
step produces the executable by means of calling the GNAT binder, compiling
its output, and calling gcc with the needed object files and libraries to
link the executable.  The -o switch is passed to the linker to name the
resulting executable file.

As the example suggests, the gcc command recognizes the extension .adb as
an indication of an Ada source file and calls the appropriate programs
to generate an object file (hello.o or hello.obj) and an Ada Library
Information (ALI) file (hello.ali) containing dependency information used
by the binder to verify consistency and determine order of elaboration.
The "ali" extension is recognized by gnatbl as the ALI file of the main
procedure or function, and gnatbl uses it to create a file called the
bind file, and to gather all the needed object files for linking.


Gnatbl
-----
The program gnatbl is being provided on a temporary basis to simplify
binding and linking using the RTL in the most simple situations.  It will
be replaced later by a more complete utility to build a complete Ada
system.  Gnatbl calls gnatbind which creates a C file (b_hello.c in our
simple example) containing calls to all of the elaboration routines.
Gnatbind is described more fully below.  The typical use of GNAT (currently
-- in the presence of gnatbl) to construct a program consisting of a mix
of Ada and C sources is to compile all of the sources using "gcc -c" to
generate object (.o or .obj) files.  In the case of Ada sources, ALI files
with the extension .ali are also produced.  Then gnatbl is used to construct
the executable.  All arguments to gnatbl are simply passed through to gcc
to link the objects together, with the exception of a file name with the
.ali extension.  Such an argument is presumed to be the ALI file of the
main procedure of the program.  When gnatbl sees a .ali file it calls gnatbind
to create the bind file, compiles the bind file, extracts a list of needed
object files from the bind file, and replaces the .ali argument with the
a list of object files (the result of compiling the bind file and the list
extracted from the bind file) in the gcc command it makes.  As a quick
illustration consider a program comprising main.adb, foo.adb and bar.c.
After compiling these sources into object files, the command (under Unix)

gnatbl -o main main.ali bar.o

would cause gnatbl to:
  call "gnatbind main.ali", generating b_main.c
  call "gcc -c b_main.c"
  call "gcc -o b_main.o main.o foo.o bar.o (+ gnat library args)"

In the last step, the "main.ali" argument has been replaced by all of the
object files needed by main (the binder file, main itself, and foo -- upon
which main depends). All other gnatbl arguments are passed through unchanged
to gcc.  Finally a -l and a -L argument are added to the end of the gcc call
to point it to the gnatlib library.  (Under OS/2, the command line and
behavior of gnatbl is similar.)

A current limitation of the very simplistic gnatbl is that the main program
must be Ada and that it depends on all of the necessary library units.  In
other words, there can be only one .ali file listed and it must be the
main program.  This particularly restricts gnatbl's use when a routine written
in another language calls an Ada subprogram which is not also called from
Ada.


Using the Binder.
-----------------

In the "Hello World" example, if gnatbl were not used, the second step
would have been to call the binder directly with the command:

       gnatbind hello.ali

This command generates a file named b_hello.c which needs to be compiled and
linked together with hello.o (or hello.obj).  The file b_hello.c contains
a program which contains calls to all of the elaboration routines of all
of the units required by the subprogram whose ALI file is given on the command
line.  Then it calls the Ada subprogram itself.  By default, this C function
is called "main".  (For other options, see the section on options below.)
The program gnatbind works by recursively processing the ALI files of all
of the units that are needed.  These ALI files are found using the search
path mechanism described below.  Since object and ALI files are always
kept together, the object files needed for linking are found at the same
time and are listed in a comment at the end of the bind file.  This is where
gnatbl finds the list of object files required.

Using gcc to compile.
---------------------

In the usual procedures for using GNAT, Ada source programs are compiled into
object files using the driver program 'gcc' with the option '-c' (compile
only). Gcc recognizes the ada filename extensions .ads and .adb (discussed
more thoroughly below) and calls the actual compiler, 'gnat1' to compile
the source file.  Gcc has many switches which you will need your gcc
documentation to learn about.  In addition, gcc passes gnat1 switches
through to gnat1.  These (with a couple of exceptional abbreviations) are
spelled on the gcc command line by "-gnatXXX".  Thus

        gcc -c -gnata foo.adb

causes gcc to call the Ada compiler gnat1 with gnat1's '-a' switch; the '-c'
is understood by gcc to mean that it is done after producing the object file
(it won't try to link).  The output of this command is the object and ALI
files for foo.

In the future, the gcc and the GNAT-specific switches will be more fully
integrated.  At this time, there is the "-gnatXXX" mechanism for passing
switches through to gnat1.  Some of these switches are described in
specific sections of this document; a more complete discussion is in the
options section below.  Note that gcc passes these switches to gnat1
with the "gnat" prefix, where it is stripped off.  This means that
when gnat1 is executed the "gnat" prefix is required; but in all of the
documentation the switches are described without the prefix.

Three gcc options are translated to gnat1 arguments when seen on the gcc
command line.  These are "k8" (file name limit), "83" (Ada83 syntax) and
"w" (warning mode). Thus, the following commands are identical:

     gcc -ws -k8 file.adb
     gcc -gnatws -gnatk8 file.adb

i.e., both of them suppress warning messages from GNAT, and expect file names
to be 8 characters long at most (see below for usage).

In addition, the following gcc switches are passed through and recognized by 
gnat1 with the same effects as in cc1 (as for C files): "-g*" (other than
"-gnat*"); "-O*"; "-p"; "-pg"; "-f*"; "-d*"; "-S".  For example, 

      gcc -c -g math.adb

will generate debugging information that can be used with the debugger gdb
(see below).

The other flags that control gcc itself (notably -B and -c) and the 
assembler, behave as usual. Please consult your GCC documentation for details.


Using gcc for syntax checking
------------------------------

The current release of GNAT implements the full Ada 9X grammar as described in 
annotated Ada Reference Manual for Ada 9X (AARM, version 4.0). We think the
parser gives excellent error messages (try it and see!) and is pleasantly 
fast (again, try and see!).

To run GNAT in syntax checking only mode, use the switch "s",
that is to say, enter the command:

	gcc -c -gnats file

where file is the name of the file to be checked. (Under Unix, wild cards can
be used to check a set of files, as in *.adb.)  Note that the 'compile only'
flag has to be given for gcc, as well as the 'syntax only' flag, which is
GNAT-specific.  We will remove this redundancy in subsequent releases. 

The syntax checker is complete, and quite robust. If you manage
to blow it up, or if it fails to diagnose an error, or lets a syntactically
invalid program through, definitely let us know (see separate section below). 
If you find an error message you think could be improved, let us know as well. 
Of course, no compiler can ever have perfect error messages (that would involve
mind reading), but we are committed to doing as well as possible, so we are
happy to get suggestions in this department.

Using gcc for semantics checking
--------------------------------

The command to perform semantic checking is:

	gcc -c -gnatc file

To operate in this mode, since WITH'ed files must be accessed, the GNAT
semantic restrictions on file structuring must be followed:

     o	The needed source files must be accessible.  See the section
        below on search paths.

     o	Each file must contain only one compilation unit.
	See the section below on file name rules.

     o	The file name and unit name must match as described below, under
        File name rules.

Note that the use of search paths and the flexibility of the File name
rules will increase in the future as described in the sections on these
facilities.

The coverage of semantic checks is still incomplete, and the system
is not very robust in the presence of semantically illegal programs.
Nevertheless, this release supports many more features of Ada9X than the
previous one, and semantic checking is correspondingly more extensive. 

When you run in this mode, you may get "not implemented yet" messages,
blowups, undetected semantic errors, etc. Don't bother to tell us about any
of these -- we know only too well what still needs to be worked on! 

Here, use of the 'report errors immediately' switch ("-e", i.e., "-gnate" on
the gcc command line) will help pinpoint the source of the trouble if the
system misbehaves. 

Search paths and the Run Time Library (RTL)
-------------------------------------------

With GNAT's source based library system, the compiler must be able to find
source files for units that are needed by the unit being compiled.  Also,
during binding, ALI files are needed to do the required checking of
compilation order and to determine elaboration requirements.  Both the
compiler and the binder use search paths to locate the files that they need.
The rules are straightforward.

The compiler compiles one source file whose name must be givien explicitly
on the command line (i.e. there is no searching done for this file).  All
other source files that are needed (the most common being the specs of
WITH'ed units) are found by looking in the following directories: 

   o The first directory searched is the directory containing the source
     file of the main unit being compiled (the file name on the command
     line).

   o (UNIMPLEMENTED SO FAR) Next, the compiler looks in each directory
     named by a "-I" option given to gcc (in the order given on the
     command line).

   o Then the compiler looks in each of the directories listed in the value
     of the ADA_INCLUDE_PATH environment variable.  This value is constructed
     exactly as the PATH environment variable -- a list of directory names
     separated by ':' or ';' (Unix or OS/2, respectively) characters. Under
     OS/2, this mechanism is used to locate the RTL source files in place of
     the default location described next for Unix.

   o (Unix only) Finally the compiler looks in the default location for
     the GNAT Run Time Library (RTL) source files that is determined at the
     time that GNAT is built and installed on your system.

The compiler outputs its object files and ALI files in the current working
directory (NOTE: the object file can be redirected with the -o option;
however, gcc and gnat1 have not been coordinated on this so the ALI file
will not go to the right place -- DON'T DO THIS).

The binder takes the name of an ALI file as its argument and needs to locate
other ALI files in its recursive processing.  These are found in the
following directories:

   o First, the current working directory is searched.

   o (UNIMPLEMENTED SO FAR) Next, the binder looks in directories named
     in "-L" options on the gnatbind command line (in the order given).

   o Next, the binder looks in each of the directories listed in the value
     of the ADA_OBJECTS_PATH environment variable.  This value is constructed
     exactly as the PATH environment variable -- a list of directory names
     separated by ':' or ';' (Unix or OS/2, respectively) characters. Under
     OS/2, this mechanism is used to locate the RTL object files in place of
     the default location described next for Unix.

   o (Unix only) Finally the binder looks in the default location for
     the GNAT Run Time Library (RTL) object files that is determined at the
     time that GNAT is built and installed on your system.

The binder generates the bind file (a C language source file) in the
current working directory.

The packages Ada, System, and Interfaces and their children make up the GNAT
Run Time Library, togther with the simple IO package used in the "Hello
World" example.  The sources for these units are needed by the compiler
and are kept together in one directory (not all of the bodies are needed,
but all of the sources are kept together anyway).  The ALI files and object
files generated by compiling the RTL are needed by the binder and the linker,
and are kept together in one directory (typically different from the
directory containing the sources).  In a normal installation, the user will
not need to specify these directory names when compiling or binding (or
binding and linking with gnatbl -- though the call to the linker contains
explicit pathnames of the object files).  Either the environment variables
(OS/2) or the builtin defaults will cause these files to be found.

Besides the assistance in using the RTL, a major use of search paths is
in compiling sources from multiple directories.  This can make development
environments much more flexible.

The user might use the search paths to experiment with alternative RTLs, or
to create new libraries (not the technical Ada meaning here).


Options.
--------

Error reporting, as well as other aspects of the behavior of the system,
are controlled by the following flags. All of these must be entered with
the prefix '-gnat'. For example, '-gnatv83' specifies verbose mode for
output, and Ada83 syntax checking. 

  a	  Assertions enabled. Pragma Assert and Debug to be activated.
  b	  Generate brief messages to stderr even if verbose mode set.
  c	  Check syntax and semantics only (no code generation attempted)
  e	  Error messages generated immediately, not saved up till end
  f	  Full errors. Normally only the first error on each line is reported.
  g	  GNAT style checks enabled - col alignment, spacing, capitalization.
	  See any source file for examples.
  ix	  Identifier char set (x=1/2/3/4/p/f/n/w) default = i1 (Latin-1)
	    1-4 = Latin 1-4, p = IBM PC, f/n = full/no, upper w=wide_character
  knnn	  Limit file names to k characters (k = krunch)
  l	  Output full source listing with embedded error messages
  mnnn	  Limit number of detected errors to nnn (1-999)
  n	  No inlining of subprograms (ignore pragma Inline)
  p	  Automatic suppression of all run-time checks mentioned in LRM 11.7
  r	  Reference manual column layout required
  s	  Syntax check only
  t	  Do semantic processing even if there are syntax errors.
  u	  List units for this compilation
  v	  Verbose mode. Full error output with source lines to stdout.
  wx	  Warning mode. s = suppress, e = treat as error
  83	  Enforce Ada 83 restrictions
  sfile	  Source file names (wild cards allowed for multiple files)

Some of these options are explained in more detail elsewhere in this document.
For full information, refer to file usage.adb in this distribution.

For first-time users, and for first-compilation attempts, the following mode
of operation is recommended:

      gcc -c -gnatc lets_try_this.adb



Constraint Checking and Pragma Suppress
---------------------------------------
In the current version there are some checks performed that are mentioned in
the LRM in section 11.7. These are:

range checks on signed integer and enumeration types
  (assignment, in parameters and initial values in object declarations)
index checks
access checks

Since this is relatively new, there might still be some cases where exceptions
are raised where they shouldn't. To disable constraint checks, compile the
program with the "-gnatp" option. This is equivalent to having Pragma suppress
applied to everything. Gdb can be used to find where the exception was raised.
See the section on  "Using gdb" for further information.

Order of Compilation Issues.
----------------------------

If, in our example, there were a spec for the hello procedure, it would
be contained in the file "hello.ads"; yet this file would not need to be
explicitly compiled.  This is the result of the model we chose to implement
library management. Details of the model can be found in file gnote1. Some of
the unexpected consequences of the model (unexpected from the point of view
of existing Ada compiler systems) are the following: 

     o	There is no point in compiling generics or specifications (except for
	package specifications with no bodies), since these are compiled as
	needed by clients. If you do attempt a useless compilation, you will
	get a warning message. It is also useless to compile subunits in this
	mode, since they are compiled as needed by the parent.

     o	There are no order of compilation requirements, and performing a
	compilation never obsoletes anything. The only way you can obsolete
	something and require recompilations is if one of the relevant source
	files is modified.

     o	There is no library as such, apart from the .ali files, whose format 
	is also described in libfmt.ads. For now, we find it convenient to
	create separate .ali files, but eventually the information therein may
	be incorporated into the object file directly.

     o	When you compile a unit, the source files for the specs of all 
	units that it WITH's, all its subunits, and the bodies of any
	generics it instantiates must be around (findable by the search
        paths mechanism described above), or you will get a fatal error
	message.

The above may seem surprising. Just to provide one immediate assurance,
all of this does not mean that we are violating Ada's strict consistency 
rules; they are enforced instead by the binder. 

File Name Rules
---------------

The current version of GNAT requires that file names match compilation unit
names. The matching rules are as follows:

     o	The file name is obtained by replacing dots in the unit name with
	minus signs, and adding a suffix distinguishing bodies and specs.
	The suffix for specs is ".ads" and for bodies is ".adb".

	For example, the unchecked deallocation files would be called:

	    unchecked_deallocation.ads
	    unchecked_deallocation.adb

	in a modern system with no arbitrary file name length restrictions 
	(most systems that support GCC are in this category, e.g., most
	Unixes, OS/2, NT, Nextstep).

     o	When running under primitive systems (like OS/2 under FAT) which
	permit only short file names, the file name itself gets crunched
	to 8 characters.  The exact details of the crunching algorithm
	are in the full documentation. You can always find out the name
	it expects by compiling it (since it warns you if it's wrong).
	Briefly:

	  Only the first and last components of a subunit name are retained

	  If there are no - or _ characters in the result, it is merely
	  truncated to 8 characters.

	  If there are - or _ characters, then each piece is truncated to
	  the same length so that the total is 8 characters, favoring later
	  components if there is a character left over.

	In OS/2 under FAT, the unchecked deallocation files names would be
	abbreviated:

	    unc_deal.ads
	    unc_deal.adb

Of course the DOS-like limitations end up restricting the choice of unit names,
since file names must be unique. As noted earlier, the final system will also
have the option of providing a centralized file name directory (a kind of
vestigial library) to avoid these restrictions, and allow complete freedom
in choice of file names.

Compiling Files With Several Compilation Units.
-----------------------------------------------

GNAT can only deal with files that contain a single Ada compilation unit.
However, since it is an established style for certain types of programs
to contain more than one compilation in a file, such as in test suites,
a simple utility program, "gnatsplit", is provided to preprocess the file
and split it several other files, one for each compilation unit.
gnatsplit takes a filename with an extension of either "ads" or "adb".
This name can basically be anything.

Usage : gnatsplit [-ksw] filename [directory]
 
  k         limit filenames to 8 characters
  s         generate a compilation script
  w         overwrite existing filenames
  filename  source file with .ads or .adb extension
  directory directory to place split files (default is the current directory)

For example, assume archive.adb contains package spec part1, package body
part1, package spec part2, package body part2.adb and subprogram part3 in
any sequence.

"gnatsplit archive.adb" will create five files in the current directory called
part1.ads, part1.adb, part2.ads, part2.adb, part3.adb. The optional directory
argument places all the split files in that directory rather than the current
directory. The directory must already exist otherwise gnatsplit will reject it.

If at least one of the files to be split already exists, gnatsplit will issue a
message and exit unless the -w flag is used to overwrite existing files.

The -s flag generates a script which can be used to compile all the units
contained in the original source file.

The -k flag krunches the names of the units to be 8 characters followed by the
ads or adb extension.

Under OS/2, if you want to specify more than one flag, you need to specify them
separately.  For example, if you want to split archive.adb and specify both the
-s and the -w flags, type "gnatsplit -s -w archive.adb" instead of
"gnatsplit -sw archive.adb".

Cross Reference Tool.
---------------------

The GNAT system provides a standalone tool, gnatf, which allows for
syntax and semantics checking without any code generation. This is
somewhat faster than using "gcc -gnatc". However, the real point of
gnatf is that it contains a cross reference (xref) tool.

The goal of the xref tool is:

 1. Give precise information about all declared entities
    (where they are defined and where they are used).

 2. Emit warnings if an entity is defined but never used or
    a with clause is unnecessary, misplaced or redundant
    (more on this later).

Usage : gnatf [-x[1-4]] filenames

        The -x[1-4] flags controls the amount of information given
        by the xref tool. Flags -x1 and -x2 control the level of
        warnings generated. These warnings are both output on the
        screen and in the xref file, if it's requested with the
        options -x3 or -x4.

        Note: the standard gnat options that do not concern code
              generation are still available in gnatf. However,
              they should not be preceeded by -gnat, so to do syntax
              only checking with gnatf, use``gnatf -s file.adb'', not
              ``gnatf -gnats file.adb''.

Flags usage:

  x1        issues warnings for unnecessary, misplaced or redundant
            ``with'' clauses. Specifically, a warning message is
            generated in the following cases:
              - A compilation unit which is withed but never used.

              - A compilation unit which is withed in a body (resp.
                subunit) if the same with clause already appears in
                the spec (resp. spec or body for subunits).

              - A compilation unit which is withed within a spec
                but is used only by the body or a subunit.

  x2        issues warnings on unused entities, that is entities that
            are declared but never used. Note that we give *no*
            warnings for unreferenced entities like:
              - Record fields, since they could be referenced indirectly
                by an aggregate.

              - Enumeration entities, since they could be referenced
                indirectly by enumeration ranges:
                     for i in Color'First .. Color'Last

              - Loop parameters
                    for i in 1 .. 80 loop
                       Put ('x');
                    end loop;

  x3   
  x4        generate a cross-reference table. The only difference between
            -x3 and -x4 is that the option -x4 gives the entity kind for
            every entity appearing in the xref. When the switches -x3 or
            -x4 are activated a cross reference file is created. The name
            of the xref file is ``X.ref''.
 
  filenames is a list of Ada source files. Full GNAT compatibility
            is preserved: For instance, to create the xref for
            a full Ada program it's sufficient to call gnatf with the
            .adb files (bodies), the required specs and subunits are 
            loaded automatically. Likewise, to create the xref for a
            chunk of the program, it suffices to list the appropriate
            .adb files. If you are interested in the xref of a few
            package specs in the program, then "filenames" should consist
            of those specs. Only other withed specs will be loaded and no
            bodies will be examined. 


Cross reference file structure:

  The xref file is divided into various sections. There is one section
  for each compilation unit explicitly requested in ``filenames''. We
  call these units, the RUs, short for requested units.  There is also
  one section for each AU, short for auxiliary unit, that is, those
  compilation units that get implicitly loaded by the compiler, but
  whose compilation has not been explicitly requested by the user.
  Specs of withed packages are typical auxiliary units.

  All entities belonging to RUs appear in the xref file. However, only the
  entities defined in AUs that are used in RUs apper in the xref file.
  Their order is the order of declaration in the source files.

  The sections in the xref referring to RUs and AUs are respectively denoted:

            %%% unit %%%   for a RU.

            --- unit ---   for an AU.

  Note: An entitiy defined inside a generic and used through a generic
  instantiation, is listed under the xref section of the generic unit.

  Example: Follows a list of files and the corresponding cross reference.
  ^^^^^^^
                        test.adb
                        ^^^^^^^^
            01  with Part1;  --  unused
            02  with Part2; use Part2;
            03  procedure Test is
            04
            05     Variable: Number;
            06     type Client is record
            07        Number : Integer;
            08        State  : Boolean;
            09     end record;
            10     type Color is (Red, Green);  -- unused
            11     My_Client : Client;
            12
            13  begin
            14     My_Client.Number := 1;
            15     My_Client.State  := True;
            16     Variable := 20;
            17     Variable := Variable + Variable;
            18  end;
                      part1.ads
                      ^^^^^^^^^
            01  package Part1 is
            02     type Useless is new Integer;
            03  end;
                      part2.ads
                      ^^^^^^^^^
            01  package Part2 is
            02     type Number is new Integer range 1 .. 1000;
            03     The_Number : constant := 42;
            04  end;

  The result of invoking ``gnatf -x3 test.adb'' is the following
  (just skim the X.ref, explanations follow):

                    Warnings on the screen
                    ^^^^^^^^^^^^^^^^^^^^^^
             "test.adb", line 1(6): warning: "Part1" withed but unused
             "test.adb", line 3(11): warning: "Test" unused
             "test.adb", line 10(9): warning: "Color" unused

                           X.ref
                           ^^^^^
             01 %%%% procedure /test/ SPEC & BODY: test.adb %%%%
             02 /test/ 3 >>> Warning: unused <<<
             03 /test#variable/ 5 
             04      test.adb {16 17}
             05 /test#client/ 6 
             06      test.adb {11}
             07 /test#client.number/ 7 
             08      test.adb {14}
             09 /test#client.state/ 8 
             10      test.adb {15}
             11 /test#color/ 10 >>> Warning: unused <<<
             12 /test#red/ 10 
             13 /test#green/ 10 
             14 /test#my_client/ 11 
             15      test.adb {14 15}
             16
             17 ---- package /part1/ SPEC: part1.ads ----
             18 >>> Warning: withed but unused in test.adb <<<
             19 /part1/ 1 
             20      test.adb {1}
             21
             22 ---- package /part2/ SPEC: part2.ads ----
             23 /part2/ 1 
             24      test.adb {2}
             25 /part2.number/ 2 
             26      test.adb {5}

  Explanations:
  ^^^^^^^^^^^^
  File ``test'' is the only RU (requested unit). AUs (auxiliary
  units are packages ``part1'' and ``part2''. Entry

             03  /test#variable/ 5
             04       test.adb {16 17}

  means that ``Variable'' is an entity defined in ``Test'' not visible
  outside the scope of ``Test'' (hence the ``#''). ``Variable'' is
  defined in line 5 and used in lines 16 and 17 in file ``test.adb''.
  When an entity is visible outside its scope the xref puts a ``.''
  instead of a ``#''. For instance

             25 /part2.number/ 2 
             26      test.adb {5}

  means that ``Number'' is defined in package ``Part2'' at line 2, it's
  visible outside of ``Part2'' and it's used in file ``test.adb'' at
  line 5. Note that entity ``Number'' could be used in units other than
  ``Test'' but that information is not contained in the Xref since it
  was not requested.

Implementation of Intrinsic Functions.
--------------------------------------
GNAT version 1.79 begins to implement intrinsic functions. In particular,
the shift functions predefined in Interfaces are now implemented.

The implementation is quite general. You can define shift operations (i.e.
one of the five operations, Shift_Left, Shift_Right, Shift_Right_Arithmetic,
Rotate_Left, Rotate_Right) on any integer type, signed or unsigned, whose
Size is 8, 16, 32 or 64 bits, and then provide an appropriate pragma Import
Intrinsic, and everything will work.

In other words, the package Interfaces is not using any special magic, and
you can do exactly what it does to make shift operations available for any
integer types that meet the size criteria (shift operations for wierd-sized
integers seem too marginal to worry about!)

Example:

   type My_Type is new Integer;

   function Shift_Left (Val : My_Type; Count : Natural) return My_Type;
   pragma Import (Intrinsic, Shift_Left);

The exact requirements on the pragma Import are as follows:

  The function must have one of the five standard names

  There must be two arguments

  The first argument can be of any integer type with a size of 8, 16, 32, 64
  either signed or unsigned.

  The return type must be the same as the first argument type

  The second argument (the shift count), can be of any integer type

Getting Internal Debugging Information.
---------------------------------------

Most compilers have secret internal debugging switches and modes. GNAT is
no exception, except that nothing about GNAT is secret. A summary and full
description of all the compiler/binder debug flags can be found in the file
debug.adb. You will have to get the sources of the compiler to see the full
detailed effects of these, but feel free to experiment with them.

The switches that print the source of the program (reconstructed from the
internal tree) are of general interest, as are the options to print the full
internal tree, and the entity table (that is to say, the symbol table
information). 

When GNAT crashes. 
------------------

There are several things you can do when GNAT does the unexpected while
compiling your Ada program, such as aborting with a segmentation fault
or illegal memory access, raising an internal exception, or otherwise
terminating abnormally. The following lines of action are of course
palliatives that will become unecessary as the system becomes more complete
and robust. The following strategies are presented in increasing order of
difficulty, corresponding to the sophistication of the user, and her
curiosity about the functioning of the compiler.

  1. run gcc with the -gnatf and -gnate switches.
     The 'f' switch causes all errors on a given line to be reported. In
     its absence, only the first error on a line is displayed. 

     The 'e' switch causes errors to be displayed as soon as they are 
     encountered, rather than after compilation is terminated.

Often this will be enough to identify the construct that produced the crash.

  2. run gcc with -v (verbose) switch. In this mode, gcc produces ongoing 
     information about progress of the compilation and in particular the name 
     of each procedure as it begins to generate code for it. This switch
     allows you to find which Ada procedure it was compiling when it ran into 
     a code generation problem. 

  3. run gcc with the -gnatdc switch. This is a GNAT-specific switch that
     does for the front-end what -v does for the back-end. The system prints
     the name of each unit, either compilation unit or nested unit, as it
     is being analyzed. 

  4. On systems that have gdb available (like most Unix systems), you can run
     gdb directly on the gnat1 executable. Gnat1 is the front-end of
     GNAT, and can be run independently (normally it is just called from gcc).
     You can use gdb on gnat1 as you would on a C program (but see below for
     caveats). The "where" command is the first line of attack; the variable
     "lineno"  (seen by "print lineno") used by the second phase of gnat1
     and by the gcc back-end, indicates the source line at which the execution
     stopped, and "input_filename" the name of the source file.

Using gdb on systems that provide it (currently not available under OS/2)
-------------------------------------------------------------------------

Gdb awaits modifications to handle Ada properly, and for now can only be
used as it would be for a c program. (Someone is working on the proper
extensions, and these will appear in subsequent releases.) In the meantime,
the following naming conventions will allow you to find the Ada entities
defined in your program:

a)  The names of all entities (variables, subprograms, etc.) are converted to
    lower case. 

b)  Entities that appear in library package declarations have the name
    package_name__subprogram_name (Note the two underscores separating 
    package name from subprogram name). 

Exceptions can be caught by breaking in the "catch_except" routine and then
doing a "bt" or "where" command.

Features supported/unsupported
------------------------------
A full listing of features supported/unsupported is available separately in
the file "features" included in the distribution. Note that this usually
changes with each distribution, so read often.

Files.
------

If you want to examine the workings of the GNAT system, the following
haiku-like description of its organization might be of minimal use:

File with prefix "sc" contain the lexical scanner.

All files prefixed with "par" are components of the parser. The numbers 
correspond to chapters of the Ada83 LRM (or the corresponding sections of 
the Ada9X LRM).  For example, parsing of select statements can be found 
in par-ch9.

All files prefixed with "sem" perform semantic analysis. Same numbering scheme.
For example, all issues involving context clauses can be found in sem_ch10.

All files prefixed with "exp" perform AST normalization and expansion. 
For example, the construction of record initialization procedures is 
done in exp_ch3.

The files prefixed with "bind" implement the binder, which verifies the
consistency of the compilation, determines an order of elaboration, and
generates the bind file.

The file atree details the low-level data structures used by the front-end.
The file sinfo details the structure of the AST as produced by the parser.
The file einfo details the attributes of all entities, computed during
semantic analysis.

Library management issues are dealt with in files with prefix "lib".

Files with prefix a- are GNAT-specific C files. They are the components of
Gigi (gnat-to-gnu), the program that translates the Ada AST into gcc tree 
fragments. Gigi makes use of C versions of atree, einfo and sinfo, called 
a-atree.[ch], a-einfo.[ch] and a-sinfo.h respectively.

All the other .c files are modifications of common GCC files. 

Happy browsing!


Copyright Considerations
------------------------

For now, everything is copyrighted by NYU, using the GNU public license. This
means that you can copy everything freely, but you can't incorporate the code
directly into a commercial program. For more information on the GNU license,
see the file header. One important note is that it will be possible
to use GNAT to generate software that is not itself covered by the GNU license.
Eventually the copyright will be transferred to the Free Software Foundation,
so that GNAT can be distributed directly by FSF under the same restrictions (or
what we like to think of as lack of restrictions!).

How to Get in Touch with Us
---------------------------

To get on our external INTERNET mailing list, send a message to:

	gnat-request@cs.nyu.edu

SUBMITTING BUG REPORTS

We welcome bug reports, they are of course a vital part of the process of
getting GNAT into solid shape. You will help us (and make it more likely
that you receive a timely response) if you follow these guidelines.

We only receive bug reports by internet, addressed to gnat-report@cs.nyu.edu.
At the moment we cannot process bug reports from any other source.

Please put one bug in a message, and add a short but specific subject (a
general subject like "GNAT bug" is not so useful, a title like "bug in
visibility with generics" is more useful).

Please include full sources. We can't duplicate errors without the full
sources. Include all sources in the single email message with appropriate
indications in the multiple file cases, see below.

Please send all sources in plain ASCII form, we can't process compressed,
uuencoded etc. messages in our current form (they have to go through extra
steps, and easily get lost, separated from the author etc during this process).

Please include COMPLETE identification of the version of the system you are
running.

To be maximally helpful, for a report that contains multiple separate
compilation units, and hence multiple files, submit them in the form of
a single file that is acceptable input to gnatsplit, i.e. contains no
non-Ada text. If you use banners to separate the files, make sure they
are composed entirely of blank lines or Ada comments.

If you want to be maximally helpful, try to reduce your example to a simple one
but DON'T spend too much time doing this. Especially when you are reporting
a blow up during compilation, rather than bad code generated, we can in 
practice work with big sources if you have trouble narrowing things down.

When we receive a bug report, we take a preliminary look to categorize it
into one of the following:

   1.  Pilot error, documentation problems, installation problems etc.

   2.  Interesting comment, suggestion etc, but not a bug

   3.  Bug that we already know about

   4.  Bug that is already fixed in our development version

   5.  Obvious bug that we correct immediately in our development version

   6.  Real genuine new unfixed bug.

In the first 5 cases, you will get a message telling you the status. In the
6th case only, we assign a bug tracking number of the form mmdd-nnn, where
mmdd is the date of receipt, and nnn is a serial number (highest value so
far 005, but you never know!) In this case, the release notes will tell you
what the status of the bug is, and also we will send you a message when it
is fixed.

To send reports to us on the system, or ask questions, send messages to

	gnat-report@cs.nyu.edu

To contact team members, send messages to:

	dewar@cs.nyu.edu
	schonberg@cs.nyu.edu

To obtain electronically the latest version of the system, FTP from:

	cs.nyu.edu (directory pub/gnat)

This FTP directory also includes full sources for the system, full
documentation and technical notes, as well as executables of the system
for several targets. We are sorry that our limited resources do not allow
us to distribute the system through other media.

We trust that this information will be mirrored at other FTP sites around 
the world (we encourage such mirroring to occur), which will make it easier
for users in other continents to obtain the GNAT system without heavy
communication uncertainties.

Schedule.
---------
We will make available new releases of GNAT at 2 or 3 week intervals for the
time being. Please recall that releases of the system are still only snapshots
of work in progress. We hope that it will be of some use in the work of others,
even in its current embryonic form. 

A short gnat paper
------------------
A TeX file of a short paper describing something about the GNAT project is
included under the name gnat-paper.tex.

The GNAT development team.
---------------------------

	New York University

	     Bernard Banner (*)
	     Cyrille Comar (*)
	     Robert Dewar (*)
	     Sam Figueroa (*)
	     Richard Kenner (*)
	     Bruno LeClerc (*)
	     Brett Porter (*)
	     Gail Schenker (*)
	     Edmond Schonberg (*)

	Florida State University (Tasking runtime work)

	     Ted Baker
	     Ted Giering (*)
	     Frank Muller

	Ecole Nationale Superieure de Telecommunications

	     Franco Gasperoni (*)
	     Yvon Kermarrec
	     Laurent Pautet

	Elsewhere

	     Paul Hilfinger (*) (University of California, Berkeley)
	     Jean Pierre Rosen (*) (Paris)
	     Richard Stallman (Free Software Foundation)

(*) partially supported by the NYU GNAT project
    (ARPA, USAF, AJPO, Ada 9X project office)
