
.. _About_This_Guide:

About This Guide
~~~~~~~~~~~~~~~~

This guide has two aims. The first one is to introduce you to the Ada Semantic
Interface Specification (ASIS) and show you how you can build various useful
tools on top of ASIS. The second is to describe the ASIS implementation
for the GNAT Ada compiler.

**What This Guide Contains**

This guide contains the following chapters:


*
  :ref:`Introduction`, contains the general definition of ASIS and gives some
  examples of tools which can be built on top of ASIS.

*
  :ref:`Getting_Started`, contains a short guided tour through the
  development and use of ASIS-for-GNAT-based tools.

*
  :ref:`ASIS_Overview`, gives an overview of ASIS, allowing
  an ASIS newcomer to navigate through the ASIS definition
  (readers already familiar with ASIS can skip this section).

*
  :ref:`ASIS_Context`, defines the ASIS ``Context`` concept in
  ASIS-for-GNAT and explains how to prepare a set of Ada
  components to be processed by an ASIS application.

*
  :ref:`ASIS_Application_Templates`, describes a set of Ada source components
  provided by the ASIS-for-GNAT distribution that may be used as a basis for
  developing ASIS applications.

*
  :ref:`ASIS_Tutorials`, describes some examples included in
  the ASIS-for-GNAT distribution.

*
  :ref:`How_to_Build_Efficient_ASIS_Applications`, describes how to
  deal with 'tree swapping', a potential performance issue with ASIS
  applications.

*
  :ref:`Processing_an_Ada_Library_by_an_ASIS-Based_Tool`, shows how to use an
  ASIS tool on pre-compiled Ada libraries.

*
  :ref:`Compiling_Binding_and_Linking_Applications_with_ASIS-for-GNAT`, explains
  how to compile an ASIS application with ASIS-for-GNAT and how to create
  the resulting executable.

*
  :ref:`ASIS-for-GNAT_Warnings`, describes the warnings generated by
  the ASIS implementation.

*
  :ref:`Exception_Handling_and_Reporting_Internal_Bugs`, explains
  what happens if an ASIS implementation internal problem is detected during
  the processing of an ASIS or ASIS Extensions query

*
  :ref:`File_Naming_Conventions_and_Application_Name_Space`, explains
  which names can and cannot be used as names of ASIS application
  components.

**What You Should Know Before Reading This Guide**

This User's Guide assumes that you are familiar with Ada language, as
described in the International Standard ANSI/ISO/IEC-8652:2012(E) (hereafter
referred to as the Ada Reference Manual),
and that you have some basic experience in Ada programming with GNAT.

This User's Guide also assumes that you have ASIS-for-GNAT properly installed
for your GNAT compiler, and that you are familiar with the structure of the
ASIS-for-GNAT distribution (if not, see the top ASIS README file).

This guide does not require previous knowledge of or experience with ASIS itself.

**Related Information**

The following sources contain useful supplemental information:

*
  GNAT User's Guide, for information about the GNAT environment

*
  ASIS-for-GNAT Installation Guide

*
  The ASIS-for-GNAT Reference Manual

*
  The ASIS 95 definition, available as ISO/IEC International Standard
  15291.

*
  The Web site for the ASIS Working Group:
  `http://www.acm.org/sigada/wg/asiswg <http://www.acm.org/sigada/wg/asiswg>`_

**Conventions**

Following are examples of the typographical and graphic conventions used
in this guide:

*
  ``Functions``, ``utility program names``, ``standard names``,
  and ``classes``.

*
  ``Option flags``

*
  :file:`File Names`, :file:`button names`, and :file:`field names`.

*
  `Variables`.

*
  *Emphasis*.

*
  [optional information or parameters]

*
  Examples are described by text

  .. code-block:: ada

    and then shown this way.


Commands that are entered by the user are preceded in this manual by the
character '$' (dollar sign) followed by space. If your system
uses this sequence as a prompt, then the commands will appear exactly as
you see them in the manual. If your system uses some other prompt, then
the command will appear with the ``$`` replaced by whatever prompt
character you are using.

Full file names are shown with the '``/``' character
as the directory separator; e.g., :file:`parent-dir/subdir/myfile.adb`.
If you are using GNAT on a Windows platform, please note that
the '``\``' character should be used instead.
