File: README

package info (click to toggle)
asis 3.12p-3
  • links: PTS
  • area: main
  • in suites: potato
  • size: 6,920 kB
  • ctags: 3
  • sloc: ada: 76,459; perl: 1,330; makefile: 87
file content (449 lines) | stat: -rw-r--r-- 16,821 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
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

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. 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

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

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

   /examples  <-- ASIS application examples

      /ds        <-- a tool which can reproduce the source of an Ada
                     compilation unit from its ASIS "tree"

      /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.

   /exercises <-- Hands-On ASIS tutorials (this section is under
                  development)



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
<your_home_directory>/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 without parameter:

c:\asis-3.11w-src\install_asis

it creates an ASIS library in c:\local\asis directory and the executable
for asistant in the directory where asistant sources are located.

If you call it with 'all' parameter:

c:\asis-3.11w-src\install_asis all

it creates an ASIS library and executables for ASIS examples included in the
ASIS-for-GNAT distribution, these executables will be created in the
directories where the sources of the examples are located.

If you call it with 'clean' parameter:

c:\asis-3.11w-src\install_asis clean

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

By default, asis_install.bat creates an ASIS library in c:\local\asis. You
may choose another drive and directory for installing the ASIS library by
editing this file: you have to change the values of INSTALL_DRIVE and
INSTALL_DIR variables defined in the very beginning of this file. The ASIS
library is installed in INSTALL_DRIVE\INSTALL_DIR\asis directory.


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).



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.


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 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 examples
   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):

   cd 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:

   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.