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
|
This file describes the structure and the contents of the ASIS-for-GNAT
distribution and explains how to install ASIS-for-GNAT.
ASIS-for-GNAT Installation Guide
=================================
Contents
1. Structure of the ASIS-for-GNAT Distribution
2. Coordination between ASIS-for-GNAT and GNAT Versions
3. Building and installing ASIS-for-GNAT
4. ASIS application examples
5. Related information
===========================================================================
1. 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
(or as a Windows zip archive) named asis-[version#]-src.tgz, (or
asis-[version#]-src.zip) where [version#] is the number of the GNAT version
for which ASIS-for-GNAT is distributed, for example asis-6_0_2-src.zip.
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
/lib <-- the directory to place the ASIS library into
/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.
/documentation <-- the directory containing the ASIS-for-GNAT
documentation
/tools <-- ASIS-based tools
/asistant <-- an interactive interpreter of ASIS queries and ASIS tree
browser
/gnatcheck <-- a tool which checks its argument sources against a
given set of code style rules
/gnatelim <-- a tool which analyzes a full Ada program and detects
subprograms which are declared, but which are never
called in this program
/gnatmetric <-- a tool which counts various metrics for its argument
sources
/gnatpp <-- a pretty-printing tool
/gnatstub <-- a tool which can create an "empty", but compilable
body for an library unit declaration.
/tool_utils <-- an ASIS Utility Library, it contains various resources
that can be useful for ASIS application development,
some of these resources are used for the ASIS tools
listed above
/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
2. 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:
- Get the version number and the build date for the GNAT compiler installed in
your environment. To do this, 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[-<backend suffix>]>)
e.g. GNATLS Pro 6.0.2 (20070620-41)
- Get the version and the build date of the GNAT compiler which components are
used as a part of the ASIS implementation. Look into the source file
asis-[version#]-src/gnat/gnatvsn.ads and locate the value of the string
constant Gnat_Static_Version_String. It has the following structure
<compiler_version> (<date>)
- compare <compiler_version> and <date> parts of these two strings.
If the version numbers in the <compiler-version> parts and dates 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.
3. Building and installing ASIS-for-GNAT
-------------------------------------
The simplest, most reliable, and recommended way to build ASIS-for-GNAT
is to use the project files included in the ASIS distribution.
After unpacking the ASIS-for-GNAT archive, go to the resulting
asis-[version#]-src directory. Before actually building ASIS and the
ASIS tools with those project files, go to the gnat/ subdirectory, build
and run the program that generates the source components needed by ASIS
from the source templates, and then rename them as Ada sources:
cd gnat/
gnatmake xsnamest.adb
./xsnamest
<move> snames.ns snames.ads
<move> snames.nb snames.adb
cd ..
where <move> is a file renaming command in your system.
Then go back to the ASIS root directory and do:
gnat make -Pasis_bld
This compiles all the ASIS implementation sources, placing the objects
and ALI files in asis-[version#]-src/obj, and creating the ASIS library
in asis-[version#]-src/lib.
When this is done, you can build the ASIS tools executables. To build an
ASIS tool, go into the corresponding tool sources directory
tools/<toolname> and do:
gnat make -P<toolname>
This creates the executable for <toolname> in the tools/<toolname>
directory.
If you want to build ASIS and install it as a library to be used
with GNAT, go to the root ASIS directory and run:
make all install prefix=<install_dir>
This will create the required Ada sources from the templates present in
the gnat subdirectory, build and install the ASIS library in the
specified location. <install_dir> is the root directory of your GNAT
installation (this is the recomended way to install ASIS).
Then, in order to be able to build your own ASIS tools with the project
files, just add:
with "asis";
to a project file used by your ASIS application.
If you run in the root directory of the ASIS source distribution
asis-[version#]-src:
make install-asistant prefix=<install_dir>
this installs the ASIS interactive interpreter asistant (see
the ASIS User's guide for more details).
4. ASIS application examples
-------------------------
The ASIS-for-GNAT does not contain any special directory with ASIS application
examples. Instead, you may consider the directories with ASIS tools included
in the distribution as examples of real-life ASIS applications. Note that the
corresponding tool project files can be used as templates for creating project
files for your own ASIS application. A good starting point as a full-size ASIS
application example is the gnatstub tool.
The solutions provided for the ASIS tutorial (asis-[version#]-src/tutorial)
can be viewed as simple (introductory) ASIS application examples. The directory
asis-[version#]-src/tutorial/using_templates/metrics contains a simple
solution for the metric tool development problem (the full-size solution is
given in asis-[version#]-src/tools/gnatmetric), the directory
asis-[version#]-src/tutorial/using_templates/style_checker provides a simple
solution for the style checking tool problem (the full-size solution is given
in asis-[version#]-src/tools/gnatcheck).
5. Related information
-------------------
For more information about ASIS-for-GNAT see the following documents:
- 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.
- 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.
- 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.
|
