1This file describes the structure and the contents of the ASIS-for-GNAT 2distribution and explains how to install ASIS-for-GNAT. 3 4 5 ASIS-for-GNAT Installation Guide 6 ================================= 7 8Contents 9 101. Structure of the ASIS-for-GNAT Distribution 112. Coordination between ASIS-for-GNAT and GNAT Versions 123. Building and installing ASIS-for-GNAT 134. ASIS application examples 145. Related information 15=========================================================================== 16 171. Structure of the ASIS-for-GNAT Distribution 18 ------------------------------------------- 19 20ASIS-for-GNAT is distributed as a set of text files in ASCII format with 21UNIX-style line breaks. It includes all the sources of the ASIS-for-GNAT 22components. 23 24The ASIS-for-GNAT distribution is packaged as a UNIX tape archive file 25named asis-[version#]-src.tgz where [version#] is the number of the GNAT version 26for which ASIS-for-GNAT is distributed, for example asis-7.1.1-src.tgz. 27 28When you extract the content of this archive, you obtain the following 29directory structure: 30 31asis-[version#]-src <-- the top of the ASIS source distribution hierarchy 32 33 /asis <-- the sources of the ASIS implementation components 34 35 /lib <-- the directory to place the ASIS library into 36 37 /obj <-- the directory to be used for object and ALI files when 38 installing ASIS. Originally it contains only the 39 Makefile and the file install_asis.adb containing the 40 source of a dummy Ada unit. 41 42 /documentation <-- the directory containing the ASIS-for-GNAT 43 documentation 44 45 /tools <-- ASIS-based tools 46 47 /asistant <-- an interactive interpreter of ASIS queries and ASIS tree 48 browser 49 50 /gnatcheck <-- a tool which checks its argument sources against a 51 given set of code style rules 52 53 /gnatelim <-- a tool which analyzes a full Ada program and detects 54 subprograms which are declared, but which are never 55 called in this program 56 57 /gnatmetric <-- a tool which counts various metrics for its argument 58 sources 59 60 /gnatpp <-- a pretty-printing tool 61 62 /gnatstub <-- a tool which can create an "empty", but compilable 63 body for an library unit declaration. 64 65 /gnattest <-- a tool which can create a test infrastructure for the 66 test suites based on AUNIT testing framework. 67 68 /gnat2xml <-- a tool that translates Ada source code into XML 69 70 /tool_utils <-- an ASIS Utility Library, it contains various resources 71 that can be useful for ASIS application development, 72 some of these resources are used for the ASIS tools 73 listed above 74 75 /tutorial <-- Hands-On ASIS tutorials 76 77 /templates <-- A set of Ada source components which may be used for fast 78 development of simple ASIS-based tools or which can be reused 79 in the code of ASIS applications 80 812. Coordination between ASIS-for-GNAT and GNAT Versions 82 ---------------------------------------------------- 83 84The implementation of ASIS is always based on some persistent data structure 85produced by the underlying Ada compiler. ASIS-for-GNAT uses the tree output 86files produced by GNAT, and it incorporates some compiler components to work 87with these tree files. 88 89Each distribution of ASIS-for-GNAT corresponds to a specific version of GNAT. 90The version number is a part of the name of the archive file of the 91ASIS-for-GNAT distribution, as well as the name of the top catalog of the 92directory structure you will get when you unpack the archive. 93 94To use a given distribution of ASIS-for-GNAT, you must have the proper version 95of GNAT installed on your system. Make sure that when you update 96ASIS-for-GNAT, you also update GNAT accordingly, and vice versa. 97 98To check that your GNAT/ASIS configuration is consistent, do the following: 99 100- Get the version number and the build date for the GNAT compiler installed in 101 your environment. To do this, run the gnatls tool with -v option 102 103 $ gnatls -v 104 105 The first line of the output produced in stdout will start with: 106 107 GNATLS <compiler_version> (<date[-<backend suffix>]>) 108 109 e.g. GNATLS Pro 7.1.1 (20130109-47) 110 111- Compare this to the the version and the build date embedded in the name of 112 the ASIS source distribution. 113 114If the version numbers in the <compiler-version> parts and dates are exactly 115the same, your configuration is consistent. 116 1173. Building and installing ASIS-for-GNAT 118 ------------------------------------- 119 120After unpacking the ASIS-for-GNAT archive, go to the resulting 121asis-[version#]-src directory. 122 1233.1 Installing under Unix systems 124 ----------------------------- 125 126If you are under a Unix system (e.g. GNU/Linux, Solaris), or 127under Windows with cygwin or msys environment, use: 128 129 make all install prefix=<install_dir> 130 131This will create the required Ada sources from the templates present in 132the gnat subdirectory, build and install the ASIS library in the 133specified location. <install_dir> is the root directory of your GNAT 134installation (this is the recomended way to install ASIS). 135 136If you run in the root directory of the ASIS source distribution 137asis-[version#]-src: 138 139 make install-asistant prefix=<install_dir> 140 141this installs the ASIS interactive interpreter asistant (see 142the ASIS User's guide for more details). 143 144Then in order to be able to build your own ASIS tools with the project 145files, add: 146 147with "asis"; 148 149to a project file used by your ASIS application. 150 1513.2 Installing under Windows 152 ------------------------ 153 154Run the following commands: 155 156 gnatmake -j0 -Pasis 157 158This compiles all the ASIS implementation sources, placing the objects 159and ALI files in asis-[version#]-src/obj, and creating the ASIS library 160in asis-[version#]-src/lib. 161 162When this is done, you can build the ASIS tools executables. To build an 163ASIS tool, go into the corresponding tool sources directory 164tools\<toolname> and do: 165 166 gnatmake -j0 -P<toolname> 167 168This creates the executable for <toolname> in the tools\<toolname> 169directory. 170 171Then in order to be able to build your own ASIS tools with the project 172files, install it in the default location: 173 174 gprinstall -p asis.gpr 175 176ASIS can then be withed in other project files: 177 178 with "asis"; 179 180It is also possible to install into a specific location: 181 182 gprinstall -p --prefix=\path\to\install\dir asis.gpr 183 184The asis.gpr project will be found when setting the ADA_PROJECT_PATH: 185 186 set ADA_PROJECT_PATH=\path\to\install\dir\share\gpr 187 1884. ASIS application examples 189 ------------------------- 190The ASIS-for-GNAT does not contain any special directory with ASIS application 191examples. Instead, you may consider the directories with ASIS tools included 192in the distribution as examples of real-life ASIS applications. Note that the 193corresponding tool project files can be used as templates for creating project 194files for your own ASIS application. A good starting point as a full-size ASIS 195application example is the gnatstub tool. 196 197The solutions provided for the ASIS tutorial (asis-[version#]-src/tutorial) 198can be viewed as simple (introductory) ASIS application examples. The directory 199asis-[version#]-src/tutorial/using_templates/metrics contains a simple 200solution for the metric tool development problem (the full-size solution is 201given in asis-[version#]-src/tools/gnatmetric), the directory 202asis-[version#]-src/tutorial/using_templates/style_checker provides a simple 203solution for the style checking tool problem (the full-size solution is given 204in asis-[version#]-src/tools/gnatcheck). 205 2065. Related information 207 ------------------- 208 209For more information about ASIS-for-GNAT see the following documents: 210 211 - The ASIS-for-GNAT User's Guide explains how to build tools with 212 ASIS-for-GNAT and describes how to create and maintain an ASIS Context 213 to be used with ASIS-for-GNAT, as well as other efficiency issues. It 214 also contains a general introduction to ASIS 95. 215 216 - The ASIS-for-GNAT Reference Manual describes in full the implementation 217 choices taken on all ASIS implementation-specific issues, and lists the 218 current implementation limitations. 219 220 - New features added to the ASIS implementation for GNAT and problems 221 which have been detected and fixed are described in the files "features" 222 and "known-problems" respectively. These files are part of the GNAT 223 distribution. 224