This file describes the structure and the contents of the ASIS-for-GNAT
distribution and explains how to install ASIS-for-GNAT.

For more information about ASIS-for-GNAT see the following documents:

1. The ASIS-for-GNAT User's Guide explains how to build tools with
   ASIS-for-GNAT and describes how to create and maintain an ASIS Context
   to be used with ASIS-for-GNAT, as well as other efficiency issues. It
   also contains a general introduction to ASIS 95.

2. The ASIS-for-GNAT Reference Manual describes in full the implementation
   choices taken on all ASIS implementation-specific issues, and lists the
   current implementation limitations.

3. New features added to the ASIS implementation for GNAT and problems
   which have been detected and fixed are described in the files "features"
   and "known-problems" respectively. These files are part of the GNAT
   distribution.

                      ASIS-for-GNAT Installation  Guide
                      =================================

Contents

1. Coordination between ASIS-for-GNAT and GNAT Versions

2. Structure of the ASIS-for-GNAT Distribution

3. Installing ASIS-for-GNAT
   3.1 Standard Build and Installation Procedure
       3.1.1 Using Makefiles
       3.1.2 Using a Command Script in MS Windows
       3.1.3 Setting GNAT environment variables
   3.2 Manual Build Procedure
   3.3 Removing Old Tree Files

4. Checking the installation


1. Coordination between ASIS-for-GNAT and GNAT Versions
   ----------------------------------------------------

The implementation of ASIS is always based on some persistent data
structure produced by the underlying Ada compiler. ASIS-for-GNAT uses the
tree output files produced by GNAT, and it incorporates some compiler
components to work with these tree files.

Each distribution of ASIS-for-GNAT corresponds to a specific version of
GNAT. The version number is a part of the name of the archive file of the
ASIS-for-GNAT distribution, as well as the name of the top catalog of the
directory structure you will get when you unpack the archive.

To use a given distribution of ASIS-for-GNAT, you must have the proper
version of GNAT installed on your system.  Make sure that when you update
ASIS-for-GNAT, you also update GNAT accordingly, and vice versa.

Note, that sometimes for the same version number for the compiler there
may exist several releases having this version number (this is the case
for wavefront compiler versions). The differences between such releases
usually are completely transparent for the most of the compiler users, but
they may affect ASIS and ASIS applications. To check that your GNAT/ASIS
configuration is consistent, do the following:

- run the gnatls tool with -v option

  >gnatls -v

  The first line of the output produced in stdout will start with:

     GNATLS <compiler_version> (<date>) (e.g. GNATLS 3.12w (19990516))

- get ASIS implementor version by calling the ASIS query

     Asis.Implementation.Asis_Implementor_Version

  (you may do it from asistant, see the example in section 4). This query
  will return the (wide) string of the following format:

  ASIS <ASIS_version> for GNAT <compiler_version> (<date>)
  (e.g. ASIS 2.0.R for GNAT 3.12w (19990516)

- compare <compiler_version> and <date> parts of these two strings.

If these version strings are exactly the same, your configuration is 100%
consistent. But we do not require the compiler and ASIS versions to be exactly
the same. The important thing is that they are close enough in respect of the
structure of the compiler tree. We do not formalize this notions of
"closeness" of the compiler and ASIS versions, but the important thing
is that if your ASIS application raises Program_Error with the exception
message "Inconsistent versions of GNAT and ASIS", this means that your
GNAT/ASIS configuration is inconsistent.


2. Structure of the ASIS-for-GNAT Distribution
   -------------------------------------------

ASIS-for-GNAT is distributed as a set of text files in ASCII format with
UNIX-style line breaks. It includes all the sources of the ASIS-for-GNAT
components.

The ASIS-for-GNAT distribution is packaged as a UNIX tape archive file
named asis-[version#]-src.tar.gz, where [version#] is the number of the GNAT
version for which ASIS-for-GNAT is distributed, for example
asis-3.11w-src.tar.gz.

When you extract the content of this archive, you obtain the following
directory structure:

asis-[version#]-src <-- the top of the ASIS source distribution hierarchy

   /asis      <-- the sources of the ASIS implementation components

   /gnat      <-- the sources of the GNAT implementation components needed
                  by components of the asis-[version#]-src/asis subdirectory

   /obj       <-- the directory to be used for object and ALI files when
                  installing ASIS. Originally it contains only the
                  Makefile and the file install_asis.adb containing the
                  source of a dummy Ada unit used for ASiS installation

   /documentation  <-- the directory containing the ASIS-for-GNAT
                       documentation

   /examples  <-- ASIS application examples

      /ds        <-- a program which can reproduce the source of an Ada
                     compilation unit from its ASIS "tree", may be considered
                     as a sample pretty-printer

   /tools     <-- ASIS-based tools

      /asistant  <-- an interactive interpreter of ASIS queries and ASIS tree
                     browser

      /gnatelim  <-- a tool which analyzes a full Ada program and detects
                     subprograms which are declared, but which are never
                     called in this program.

      /gnatstub  <-- a tool which can create an "empty", but compilable
                     body for an library unit declaration.

   /tutorial <--  Hands-On ASIS tutorials

   /templates <-- A set of Ada source components which may be used for fast
                  development of simple ASIS-based tools or which can be reused
                  in the code of ASIS applications


3. Installing ASIS-for-GNAT
   ------------------------

There are two ways to install ASIS-for-GNAT: the standard and strongly
recommended way is to install it as an Ada library. The other possibility
is to use ASIS locally, as a set of third-party Ada components that you
use to build your own ASIS-based Ada program.

In both cases the first step of the installation procedure is to unpack
the ASIS-for-GNAT distribution archive and to verify that you obtain the
directory structure described in the previous section.


3.1 Standard Build and Installation Procedure
    -----------------------------------------

To install ASIS-for-GNAT as an Ada library, you may use Makefiles that are a
part of the ASIS-for-GNAT distribution. For proper use of ASIS-for-GNAT
Makefiles, you need the GNU-Make utility. If you do not have it, contact
AdaCore.

ASIS-for-GNAT Makefiles generate some UNIX commands which do not have
counterparts in Windows 95/NT and in a set of UNIX command simulators
included in the GNAT binary distribution for Windows 95/NT. To use
ASIS-for-GNAT Makefiles in MS Windows, you need a set of utilities
simulating the UNIX commands installed on your system and included in the
value of your PATH environment variable. Another possibility to install
ASIS-for-GNAT as an Ada library in MS Windows is to use a bat file
asis_install.bat located in the top asis-[version#]-src directory of the
ASIS-for-GNAT distribution. This batch file uses only standard
Windows commands and utilities included in the standard GNAT
binary distribution for MS Windows, but is more limited than the
Makefiles, especially in terms of ASIS integration with GNAT, and is not
a recommended approach.

The standard installation procedure includes building an Ada library for ASIS
and building the executable for asistant.


3.1.1 Using Makefiles
      ---------------

The ASIS-for-GNAT distribution contains the following Makefiles:

Makefile.stub - this file contains some common definitions used by other
                makefiles. If you would like to change the directory in
                which the ASIS library will be installed, edit this file
                and change the value of INSTALL_DIR variable as needed;

Makefile      - this is the top-level Makefile for ASIS-for-GNAT;

obj/Makefile  - this Makefile defines the ASIS-for-GNAT installation, that
                is, the creation of an ASIS library.

Every subdirectory of the asis-[version#]-src/examples directory and
asis-[version#]-src/asistant contains a Makefile which can be used to build the
executable for the corresponding example ASIS application (or asistant
respectively) in that subdirectory.

If you are in asis-[version#]-src directory and if you type

   make all

you will get ASIS-for-GNAT fully installed - that is, an ASIS library will
be created in the /local/asis subdirectory of your home directory (or in
C:\local\asis in the case of Windows NT/95), and asistant and all the
ASIS examples will be compiled in their respective directories, generating
the corresponding object, ALI and executable files.

In order to integrate ASIS with your GNAT installation (i.e. installing it
in the standard location for GNAT libraries and allowing its referencing
from the project files by just specifying
   with "asis";
in the dependencies section) you need to specify your compiler location in the
INSTALL_DIR Makefile variable, i.e.

   make INSTALL_DIR=<GNAT location> all

If you only want to install ASIS-for-GNAT, but not to build the
executables for the examples, go into asis-[version#]-src/obj directory and
type

   make [INSTALL_DIR=...] install

and you will get the ASIS library created and the executable for asistant
built. After this, to build the executable for any of the ASIS examples
included in the ASIS-for-GNAT distribution, you can go into the corresponding
subdirectory and type "make" without parameters.

If you are in asis-[version#]-src directory and if you type

   make clean

you will remove all the files created during ASIS-for-GNAT installation
process in subdirectory asis-[version#]-src/obj, asis-[version#]-src/asistant,
and in subdirectories containing sources of ASIS examples, but this will not
destroy an ASIS library, if it has been created. If you type "make clean" in
asis-[version#]-src/obj, asis-[version#]-src/asistant or in any subdirectory
containing ASIS examples, this will clean up only this particular
subdirectory.

Note, that you have to install ASIS-for-GNAT (that is, you have to create
an ASIS library) before building executables for any ASIS application
(including ASIS examples from the distribution). Note also, that after
cleaning up the asis-[version#]-src/obj subdirectory, you can use makefiles to
create executables for ASIS examples only if you have added the directory
containing the ASIS library to the values of ADA_INCLUDE_PATH and
ADA_OBJECTS_PATH environment variables (see below).

If you are running on MS Windows, you should have both GNAT and
ASIS-for-GNAT on disk C; otherwise Makefiles will not work correctly.

Note, that if the ASIS library installation directory existed before
installing ASIS-for-GNAT, all it old content will be lost as a result of
installing the ASIS library.

There is a limitation when installing ASIS in MS Windows: if you
would like to install ASIS on a logical drive other then C:, 'make all'
issued from the asis-[version#]-src directory will not work, so
to install ASIS you have to go into asis-[version#]-src/obj directory and
type 'make install'.


3.1.2 Using a Command Script in MS Windows
      ------------------------------------

It is recommended that even on MS Windows the Makefile-based approach is
used, which can be done using several widely available Unix toolkits.
An alternative method involves running the command file asis_install.bat
from a command shell with the directory where it is located as your current
directory. If you call it with a fully qualified path as a parameter:

asis_install <path> [all]

it creates an ASIS library in the directory specified by <path>, and the
executables for ASIS examples and ASIStant tool included in the
ASIS-for-GNAT distribution will be created in the
directories where the corresponding sources are located. If the optional
parameter 'all' is provided, the executables for the ASIS tools gnatelim
and gnatstub will be created in the directories containing the tool sources.
Note, that if <path> is not a fully qualified directory name stating from
drive letter, the installation will not work correctly.

If you call it with 'clean' parameter:

asis_install clean

it deletes all the object, ALI and exe files (if any) in the directories
containing asistant and ASIS examples.


3.1.3 Setting GNAT Environment Variables
      ----------------------------------

To complete the ASIS-for-GNAT installation as an Ada library, you have to
add the directory in which all the library files were placed during the
installation (that is, <your_home_directory>/local/asis or C:\local\asis or
another location if you have chosen some location which differs from the
default location), to the values of ADA_INCLUDE_PATH and ADA_OBJECTS_PATH
GNAT-specific environment variables (refer to the GNAT User's Guide for more
information about GNAT-specific environment variables).

Note that it is not necessary to update ADA_*_PATH environment variables if
the ASIS library has been installed in the GNAT location and the user's project
uses GNAT Project Facility.

The users of GPS can enable access to ASIS documentation files from GPS Help
menu by adding the directory asis-[version#]-src/documentation to GPS_DOC_PATH
environment variable.


3.2 Manual Build Procedure
    ----------------------

If for some reason you do not want to have ASIS-for-GNAT installed as an
Ada library, you may use it locally, as a set of source, object and ALI
files used by your particular ASIS application.

The only thing you have to do to create a local ASIS installation is
creating object and ALI files for all the Ada components making up
ASIS-for-GNAT. Assuming that you want to have all the needed object
and ALI files in asis-[version#]-src/obj, and that asis-[version#]-src/obj
is your current directory, you may do this by applying gnatmake to
a "dummy" ASIS application Install_ASIS contained in the file
asis-[version#]-src/obj/install_asis.adb. This application does nothing
but includes (by means of with_clauses) all the ASIS-for-GNAT interface
packages:

   gnatmake -c -g -O0 -I../asis -I../gnat install_asis.adb

Use of the gcc switches '-g' and '-O0' is recommended, but not obligatory.
'-g' generates the debugging information (you may get rid of it by
stripping your executables), and -O0 turns off all the optimizations.

To use a local ASIS-for-GNAT installation, you have to provide the needed
set of -I and -aO options for gnatmake (or for gcc and gnatbind
separately). See ASIS-for-GNAT User's Guide for more details.


3.3 Removing Old Tree Files
    -----------------------

The tree files (extension .adt) for older ASIS-for-GNAT versions cannot
be used with newer versions. The user must make sure that all such tree
files are deleted. If older tree file is read by ASIS-for-GNAT, it is
considered an installation error and the implementation will raise
a PROGRAM_ERROR to signify this. You will then need to create a new
version of this tree file. For more information on tree files please
refer to ASIS-for-GNAT User's Guide.


4. Checking the installation
   -------------------------

To check the installation, create the executables for the ASIS applications
included in the ASIS-for-GNAT distribution and try to run them on simple
examples.

Below are some simple examples of ASIS-for-GNAT in action, including the
output you should get if everything is installed and works correctly:

(a) Checking asistant

asistant is always built as a part of the ASIS-for-GNAT installation as an
Ada library. The executable for asistant is created in its source directory,
so you may check that it works correctly right after completing the
ASIS-for-GNAT installation by performing some simple actions in the asistant
source directory

In directory asis-[version#]-src, enter the following:

   cd tools/asistant

   gcc -c -gnatc -gnatt ../../obj/install_asis.adb

This will create the tree file for the Ada unit contained in
asis-[version#]-src/obj/install_asis.adb, which you can verify by
entering:

   ls *.adt (or 'dir *.adt' in MS Windows)

you should see:

   install_asis.adt

Now, launch asistant:

   asistant

asistant should produce the following output:

ASIStant - ASIS Tester And iNTerpreter, v1.2
(C) 1997-1999, Free Software Foundation, Inc.
  Asis Version: ASIS 2.0.R

and then enter the interactive mode; '>' is the asistant prompt. You may
input asistant commands now, below are some examples:

   >initialize ("")
   >set (lib)
   >associate (lib, "", "")
   >open (lib)
   >set (cu, compilation_unit_body ("install_asis", lib))
   >print (Unit_Full_Name (cu))

If everything works correctly, here you should see:

   Install_ASIS

Testing some more queries:

   >print (Unit_Kind (cu))

Here you should see:

   A_PROCEDURE_BODY

   >print (Unit_Class (cu))

Here you should see:

   A_PUBLIC_DECLARATION_AND_BODY

You may continue:

   > ...

To see the compiler version with which this ASIS-for-GNAT version should
be used, type:

   >print (asis_implementor_version)

and you will see the string of the following format:

   ASIS 2.0.P for GNAT 3.11w (980528)

After typing:

   >quit

you should return to the command shell again.

(b) Checking gnatstub:

Enter the following in directory asis-[version#]-src:

   cd tools
   cd gnatstub
   make

At that point you should have the executable for gnatstub built in your
current directory.

In order to create a sample body for the gnatstub component
Gnatstub.Sampler contained in gnatstub-sampler.ads, create a temporary
directory in which the stub body will be created (so as not to destroy the
body gnatstub-sampler.adb):

   mkdir tmp_dir
   ./gnatstub gnatstub-sampler.ads tmp_dir

If everything works correctly, you should see the following message
produced by gnatstub:

   body was created for gnatstub-sampler.ads

Now, try to compile it:

   cd tmp_dir
   gcc -c -gnatc -I. tmp_dir/gnatstub-sampler.adb

No error messages should be generated by GNAT for this compilation. You
may also go into tmp_dir and examine the stubbed body with your favorite
editor.