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 asisinfo.txt file describes the Copyright and Licensing issues and explains how to submit bug reports for ASIS-for-GNAT. 2. 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. 3. 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. 4. The file features.txt describes recent changes into ASIS-for-GNAT in chronological order. 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 Windows NT/95/98 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 () (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 for GNAT () (e.g. ASIS 2.0.R for GNAT 3.12w (19990516) - compare and parts of these two strings. They should be identical, otherwise your GNAT/ASIS configuration is inconsistent, and any attempt to open an ASIS context will result in raising Program_Error. 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. Currently GNU-Make is a part of a GNAT binary distribution (if you do not have it, contact ACT). 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 Windows 95/NT, 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 Windows 95/NT is to use a bat file asis_install.bat located in the top asis-[version#]-src directory of the ASIS-for-GNAT distribution. This bat file simulates all the actions performed when Makefiles are used to install ASIS-for-GNAT, but it uses only standard Windows commands and utilities included in the standard GNAT binary distribution for Windows 95/NT. 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. 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 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 activities 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 Windows NT/95, 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 (that is /local/asis or C:\local\asis) existed before installing ASIS-for-GNAT, all it old content will be lost as a result of installing an ASIS library There is currently a problem for installing ASIS in Windows 95/NT: if you would like to install ASIS on a logical drive other then C: . 'make all' issued from the asis-[version#]-src directory does not work in this case, 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 Windows NT/95 --------------------------------------- In Windows 95/NT, run the command file asis_install.bat from a command shell, having the directory where it is located as your current directory. If you call it with a fully qualified path as a parameter: asis_install it creates an ASIS library in the directory specified by , 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 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, /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). 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 Windows 95/NT) 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.