This is Info file asis_ug.info, produced by Makeinfo version 1.68 from the input file asis_ug.texi.  File: asis_ug.info, Node: Different Ways to Define an ASIS Context in ASIS-for-GNAT, Next: Consistency Problem, Prev: Creating Tree Files for Use by ASIS, Up: ASIS Context Different Ways to Define an ASIS Context in ASIS-for-GNAT ========================================================= The Asis.Ada_Environments.Associate query which defines a Context has the following profile: procedure Associate (The_Context : in out Asis.Context; Name : in Wide_String; Parameters : in Wide_String := Default_Parameters); In ASIS-for-GNAT Name does not have any special meaning, and all the properties of a Context being associated are set by the Parameters string. When making an association of an ASIS Context in ASIS-for-GNAT, you may specify the following things in the Parameters string of the Asis.Ada_Environments.Associate query: - the way of defining a set of tree files making up the Context (-C options); - the way of dealing with tree files when opening the Context and when processing ASIS queries (-F options); - the way of processing the source files during the consistency check when opening the Context (-S options): - the search path for tree files making up the Context (-T options); - the search path for source files used for calling GNAT to create a tree file on the fly (-I options); Also the association parameters may (and in some cases - have to) contain the names of tree files or directories making up search paths for tree and/or source files. Below is the overview of the Context association parameters in ASIS-for-GNAT, for full details refer to the ASIS-for-GNAT Reference Manual. Note that the set of options for the Context association is not frozen, we are open for discussing ASIS application developers' needs, and we can change or extend an existing set of options in future. The way to define a set of tree files making up a Context; the following options are possible: -C1 - "one tree" Context, defines a Context made up by a single tree file, this tree file name should be given explicitly in the Parameters string -CN - "N-trees" Context, defines a Context made up by a set of tree files, the names of the tree files making up the Context should be given explicitly in the Parameters string -CP - "partition" Context, this option is not implemented yet. The idea is to define a Context representing a complete partition, as defined in RM 95, 10.2; -CA - "all trees" Context, defines a Context made up by all the tree files in the tree search path given in the same Parameters string, if this option is set together with -FM option, ASIS can also create new tree files on the fly when processing queries yielding ASIS Compilation units. The way of dealing with tree files when opening the Context and when processing ASIS queries; the following options are possible: -FS - all the trees considered as making up a given Context are created on the fly, whether or not the corresponding tree file already exists; once created, a tree file may then be reused while the Context remains open. This option can be set only with -CA option; -FT - only pre-created trees are used, no tree file can be created by ASIS; -FM - mixed approach: if a needed tree does not exist, the attempt to create it on the fly is made. This option can only be set with -CA option. The way of processing the source files during the consistency check when opening the Context; the following options are possible: -SA - source files for all the Compilation Units belonging to the Context (except the predefined Standard package) are taken into account for consistency check when opening the Context (see 3.4 concerning the consistency problem in ASIS-for-GNAT); -SE - only existing source files for all the Compilation Units belonging to the Context are taken into account for consistency check when opening the Context (see 3.4 concerning the consistency problem in ASIS-for-GNAT); -SN - none of the source files from the underlying file system are taken into account when checking the consistency of the set of tree files making up a Context. The default options are -CA, -FT and -SA. Note, that for -C1 Context, a parameter string should contain exactly one name of a tree file. Moreover, for such a Context if during the opening of the Context this tree file could not be successfully read in because of any reason, Asis_Failed is raised. Using -I option for defining an ASIS Context is similar to using -I option when calling GNAT, -T option is used in the same way, but for tree files, for full details concerning using -T and -I options refer to the ASIS-for-GNAT Reference Manual. Note, that -T option is used only to locate existing tree files, and it has no effect for -FS Contexts. On the other side, -I option is used only to construct a set of arguments when ASIS calls GNAT to create a tree file "on the fly", it has no effect for -FT Contexts, and it cannot be used to tell ASIS where it should look for source files for ASIS Compilation Units.  File: asis_ug.info, Node: Consistency Problem, Next: Processing Several Contexts at a Time, Prev: Different Ways to Define an ASIS Context in ASIS-for-GNAT, Up: ASIS Context Consistency Problem =================== * Menu: * Inconsistent versions of ASIS and GNAT:: * Consistency of a set of tree and source files:: There are two different kinds of consistency problems existing for ASIS-for-GNAT, and both of them can show up when opening an ASIS Context. First, it may be a tree file created by another version of GNAT (see the top README file about the coordination between the GNAT and ASIS-for-GNAT versions). This means that there is an ASIS-for-GNAT installation problem. Second, it may be that the tree files are inconsistent with the existing source files or with each other.  File: asis_ug.info, Node: Inconsistent versions of ASIS and GNAT, Next: Consistency of a set of tree and source files, Up: Consistency Problem Inconsistent versions of ASIS and GNAT -------------------------------------- When ASIS-for-GNAT reads a tree file created by the version of the compiler for which a given version of ASIS-for-GNAT is not supposed to be used, ASIS treats the situation as the ASIS-for-GNAT installation problem and raises PROGRAM_ERROR with the corresponding exception message. In this case, PROGRAM_ERROR is not caught by any ASIS query and propagates outside ASIS. Note that this is not a violation of the requirement stated in the ASIS definition that only ASIS-defined exceptions are allowed to propagate outside ASIS queries, because in this case you do not have ASIS-for-GNAT properly installed and therefore you do not have a valid ASIS implementation. Note also that the real cause may be some old tree file you have forgotten to remove when reinstalling ASIS-for-GNAT. This is also considered an installation error. Be careful when using "when others" exception handler in your ASIS application: do not use it just to catch non-ASIS exceptions and to suppress them without any analysis.  File: asis_ug.info, Node: Consistency of a set of tree and source files, Prev: Inconsistent versions of ASIS and GNAT, Up: Consistency Problem Consistency of a set of tree and source files --------------------------------------------- When processing a set of more then one tree file making up the same Context, ASIS may face a consistency problem. A set of tree files is inconsistent if it contains two trees representing the same compilation unit and these trees were created with different versions of the source of this unit. A tree file is inconsistent with a source of a unit represented by this tree if the source file currently available for the unit differs from the source used to create the tree file. When opening a Context (Asis.Ada_Environmens.Open query), ASIS does the following checks for all the tree files making up the Context: * if -SA option is set for the Context, ASIS checks that for every Compilation Unit represented by a tree, the source file is available and it is the same as the source file used to create the tree (a tree file contains the reference for all the source files used to create this tree file; * if -SE option is set for the Context, then if for a Compilation Unit represented by a tree a source file is available, ASIS checks that this source is the same as the source used to create the tree. If for a Compilation Unit belonging to a Context a source file is not available, ASIS checks that all the tree files containing this unit were created with the same version of the source of this unit. * if -SN option is set for the Context, ASIS checks that all the trees were created from the same versions of the sources involved. If any of these checks fail, Asis_Failed is raised as a result of opening a Context. If the Context has been successfully opened, it ensures that ASIS will process only consistent set of tree and object files until the Context is closed (provided that this set will not be changed by some non-ASIS actions).  File: asis_ug.info, Node: Processing Several Contexts at a Time, Prev: Consistency Problem, Up: ASIS Context Processing Several Contexts at a Time ===================================== If your application processes more then one open Context at a time, and if at least one of the Contexts is defined with -FS or -FM option, be aware of the fact that all the tree files created by ASIS on the fly are placed in the current directory. Therefore, to be on the safe side when processing several opened Contexts at a time, an ASIS application should have at most one Context defined with -FS or -FM option. If it has such a Context, all the other Context should not use tree files located in the current directory.  File: asis_ug.info, Node: ASIS Interpreter asistant, Next: ASIS Application Templates, Prev: ASIS Context, Up: Top ASIS Interpreter `asistant' *************************** * Menu: * asistant introduction:: * asistant commands:: * asistant variables:: * Browsing an ASIS tree:: * Example::  File: asis_ug.info, Node: asistant introduction, Next: asistant commands, Up: ASIS Interpreter asistant `asistant' introduction ======================= `asistant' is an interactive interface to ASIS queries. It allows a user to play around with ASIS without building his own ASIS applications. It provides a simple command language which allows to define variables of ASIS types and to assign them values by calling ASIS queries. `asistant' may be very useful during learning ASIS: it allows to try different ASIS queries and to see immediately what are the results. asistant does not crash in case of any error in calling ASIS queries (such as calling a query for an inappropriate Element) - instead it reports an error and gives a user the possibility to try again. `asistant' may also be useful as a debug and "ASIS visualization" tool in a real-life ASIS application project: if an ASIS programmer has some problems in finding out which query should be used in a given situation or why a given query does not work correctly with a given piece of Ada code, he may use `asistant' to reconstruct the situation which causes problems in his ASIS application and to do some experiments with ASIS queries. Though primarily an interactive tool, `asistant' also can interpret sequences of `asistant' commands written to a file (called a script file below). `asistant' can also store in a file the log of an interactive section which can then be reused as a script file. The full documentation of `asistant' may be found in the `asistant' Users' Guide (file `asistant.ug' in the `asistant' source directory). Here only a very short overview of `asistant' usage is presented. The executable for `asistant' is created in the `asistant' source directory as a part of the standard procedure of installing ASIS-for-GNAT as an Ada library. Put this executable somewhere on your path, and then type '`asistant'' to call `asistant' in an interactive mode. As a result, the program will output a brief information about itself and then the `asistant' prompt '>' will appear: ASIStant - ASIS Tester And iNTerpreter, v1.2 (C) 1997-1999, Free Software Foundation, Inc. Asis Version: ASIS 2.0.R > Now a user can input `asistant' commands (`asistant' supports in its command language the same form of comments as Ada does, names in `asistant' are not case-sensitive): >Initialize ("") -- the ASIS Initialize query is called with an -- empty string as a parameter >set (Cont) -- the non-initialized variable Cont of the ASIS -- Context type is created >Associate (Cont, "", "") -- the ASIS Associate query with two empty -- strings as parameters is called for Cont >Open (Cont) -- the ASIS Open query is called for Cont >set (C_U, Compilation_Unit_Body ("Test", Cont)) -- the variable C_U -- of the ASIS Compilation_Unit type is created and initialized by -- the result of the call to the ASIS query Compilation_Unit_Body. -- As a result, C_U will represent an compilation unit named "Test" -- and contained in the ASIS Context named Cont >set (Unit, Unit_Declaration (C_U)) -- the variable Unit of the ASIS -- Element type is created and initialized by the result of calling -- the ASIS Unit_Declaration query >print (Unit) -- as a result of this command, the ASIS debug image of -- the current value of Unit will be printed: Element Debug_Image: A_PROCEDURE_BODY_DECLARATION located in Test (body, Unit_Id = 2, Context_Id = 1) text position : 1 : 1 - 9 : 7 Nodes: Node : 1363 - N_SUBPROGRAM_BODY R_Node : 1363 - N_SUBPROGRAM_BODY Node_Field_1 : 0 - N_EMPTY Rel_Sloc : -10 obtained from the tree .\test.atb (Tree_Id = 1) -- suppose now, that we do make an error - we call an ASIS query for -- inappropriated element: >set (Elem, Assignment_Expression (Unit)) -- ASIS will raise an exception, asistant will output the ASIS debug -- information: Exception is raised by ASIS query ASSIGNMENT_EXPRESSION. Status : VALUE_ERROR Diagnosis : Inappropriate Element Kind in Asis.Statements.Assignment_Expression -- it does not change any of the existing variables and it prompts -- a user again: > ...  File: asis_ug.info, Node: asistant commands, Next: asistant variables, Prev: asistant introduction, Up: ASIS Interpreter asistant `asistant' commands =================== The list of the `asistant' commands given in this section is incomplete and it is not supposed to be used as a reference manual for these commands. Its purpose is only to give some general feeling of what can be done with asistant: Help [(name)] - outputs the profile of the ASIS query 'name', when calling with no argument, generates a general asistant help; Set (name) - creates a (non-initialized) variable 'name' of the ASIS Context type; Set (name, expr) - evaluates the expression 'expr' (it may be any legal asistant expression, a call to some ASIS query is the most common case in practice) and creates the variable 'name' of the type and with the value of 'expr'; Print (expr) - evaluate the expression 'expr' and outputs its value; Run ("filename") - launches the script from a file "filename", reading further commands from it; Pause - paused the current script and turns asistant into interactive mode; Run - resumes a previously paused script; Browse - switches asistant into step-by-step ASIS tree browsing; Log ("filename") - opens a file "filename" for session logging Log - closes the current log file Quit [(exit-status)] - quits asistant  File: asis_ug.info, Node: asistant variables, Next: Browsing an ASIS tree, Prev: asistant commands, Up: ASIS Interpreter asistant `asistant' variables ==================== `asistant' variables have Ada-style (simple) names. Variables can be of any ASIS type and of conventional integer, boolean and string type. All the variables are created and assigned dynamically by the asistant Set command, there is no predefined variables. There is no type checking in asistant: each call to a Set command may be considered as creating the first argument from scratch and initializing it by the value provided by the second argument.  File: asis_ug.info, Node: Browsing an ASIS tree, Next: Example, Prev: asistant variables, Up: ASIS Interpreter asistant Browsing an ASIS tree ===================== Browser is invoked by calling the asistant service function BROWSE. BROWSE disables the asistant command interpreter and enables the command interpreter of Browser. The Browser 'Q' command switches back into the asistant environment by enabling asistant command interpreter and disabling the Browser interpreter. BROWSE has a single parameter of Element type, and it starts browsing the ASIS tree starting from its argument Element. BROWSE returns the result of Element type, an Element on which the process of tree browsing was stopped. So, if a user types" `> set (e0, Browse (e1))' he will start ASIS tree browsing from e1, and when he finishes the browsing, e0 will represent the last Element being visited during the browsing. If a user types `> Browse (e1)' he will be able to browse the ASIS tree, but the last element of the browsing will be discarded. Browser displays the ASIS Element it currently points at and expects one of the following keystrokes: U - one step up the ASIS tree (equivalent to calling the ASIS Enclosing_Element query); D - one step down the ASIS tree, to the left-most component of the current Element N - go to the right sibling (to the next element in the ASIS tree hierarchy) P - go to the left sibling (to the previous element in the ASIS tree hierarchy) \(D|d)(T|t) - change the form of displaying the current Element: 'D' turns ON displaying the debug image, 'd' turns it OFF. 'T' turns ON displaying the text image, 't' turns it OFF. - call the for the current Element (see 5.4.); Q - back to the asistant environment, the Browser command interpreter is disabled and the asistant command interpreter is enabled with the current Element returned as a result of the call to BROWSE; Browser immediately interprets the keystroke and displays the new current Element. If the message "Cannot go in this direction." appears, this means that traversal in this direction from current node is impossible (that is, the current node is either a terminal Element and it is not possible to go down, or it is the leftmost or the rightmost component of some element, and it is not possible to go left or right, or it is the top Element in its enclosing unit structure and it is not possible to go up). It is possible to issue some ordinary ASIS queries from inside the Browser (for example, semantic queries). The legal queries are those that accept one parameter of type Element and return Element as a result. When the user presses , he is asked to enter the query name. If the query is legal, the current Element is replaced by the result of the call to the given query with the current Element as a parameter.  File: asis_ug.info, Node: Example, Prev: Browsing an ASIS tree, Up: ASIS Interpreter asistant Example ======= Suppose we have an ASIS compilation unit Demo in the source file demo.adb: procedure Demo is function F (I : Integer) return Integer; function F (I : Integer) return Integer is begin return (I + 1); end F; N : Integer; begin N := F (3); end Demo; And suppose that the tree for this source is created in the current directory. Below is a sequence of asistant commands which does some work with this unit. asistant comments are used to explain what is doing: initialize ("") -- creating and opening a Context made up by all the tree files -- in the current directory; Set (Cont) Associate (Cont, "", "") Open (Cont) -- getting a Compilation_Unit (body) named "Demo" from this Context; Set (CU, Compilation_Unit_Body ("Demo", Cont)) -- going into the unit structure and getting to the expression -- in the right part of the assignment statements in the unit body: Set (Unit, Unit_Declaration (CU)) Set (Stmts, Body_Statements (Unit, False)) Set (Stmt, Stmts (1)) Set (Expr, Assignment_Expression (Stmt)) - outputting the debug image and the text image of this expression: Print (Expr) Print (Element_Image (Expr)) -- this expression is of A_Function_Call kind, so it's possible to ask -- for the declaration of the called function: Set (Corr_Caled_Fun, Corresponding_Called_Function (Expr)) -- the debug and the text image of the declaration of the called -- function is printed: Print (Corr_Caled_Fun) Print (Element_Image (Corr_Caled_Fun)) -- the asistant session is closed: Quit  File: asis_ug.info, Node: ASIS Application Templates, Next: ASIS Tutorials, Prev: ASIS Interpreter asistant, Up: Top ASIS Application Templates ************************** The subdirectory 'templates' of the ASIS distribution contains a set of Ada source components that can be used as templates for developing simple ASIS applications. The general idea is that one can easily build an ASIS application by adding the code performing some specific ASIS analysis in well-defined places in these templates. See the solutions provided for ASIS tutorial as the examples of the use of the templates. For more information see the README file in the 'templates' subdirectory.  File: asis_ug.info, Node: ASIS Tutorials, Next: How to Build Efficient ASIS Applications, Prev: ASIS Application Templates, Up: Top ASIS Tutorials ************** The subdirectory 'tutorial' of the ASIS distribution contains a simple hands-on ASIS tutorial which may be useful in getting the quick start with ASIS. The tutorial contains a set of simple tasks based on the asistant tool and on a set of the ASIS Application Templates provided as a part of the ASIS distribution. The complete solutions are provided for all the tasks, so the tutorial may also be considered as a set of ASIS examples. At the moment the documentation of the tutorial exists as a set of README files in the 'tutorial' subdirectory and its subdirectories. This documentation will be moved into this Guide soon.  File: asis_ug.info, Node: How to Build Efficient ASIS Applications, Next: Processing an Ada Library by an ASIS-Based Tool, Prev: ASIS Tutorials, Up: Top How to Build Efficient ASIS Applications **************************************** * Menu: * Tree Swapping as a Possible Cause of Poor Application Performance:: * Queries That Can Cause Tree Swapping:: * How to Avoid Unnecessary Tree Swapping:: * Using gnatmake to Create Tree Files::  File: asis_ug.info, Node: Tree Swapping as a Possible Cause of Poor Application Performance, Next: Queries That Can Cause Tree Swapping, Up: How to Build Efficient ASIS Applications Tree Swapping as a Possible Cause of Poor Application Performance ================================================================= If an ASIS Context is made up by more then one tree, then ASIS may switch between different trees during an ASIS application run. Switching between trees means that ASIS reads trees over and over again, and this may slow down an application considerably. Basically, there are two causes for tree swapping: 1. Processing of semantically independent units. Suppose in Context Cont we have units P and Q which do not depend on each other, and Cont does not contain any third unit depending on both P and Q. This means, that P and Q cannot be represented by the same tree. To get some information about P, ASIS needs tree p.adt to be accessed, and to get some information about Q, ASIS needs `q.adt'. Therefore, if an applications retrieves some information from P, and then starts processing of Q, ASIS has to read `q.adt'. 2. The possibility for the same unit to be presented in more then one tree. A unit may be presented by the tree created for itself, and it also is presented by all the trees created for unit which semantically depend upon a given unit. Suppose we have a library procedure Proc depending on a library package Pack, and in the set of trees making up our Context we have trees `pack.adt' and `proc.adt'. Suppose we have got some Element representing some component of Pack, when `pack.adt' was accessed by ASIS, and suppose that because of some other actions undertaken by an application ASIS changed the tree being accessed to `proc.adt'. Suppose that now the application wants to do something with the Element representing some component of Pack and obtained from `pack.adt'. Even though the unit Pack is represented by the currently accessed tree proc.adt, ASIS has to switch back to `pack.adt', because all the references into the tree structure kept as a part of the value of this Element are valid only for `pack.adt'.  File: asis_ug.info, Node: Queries That Can Cause Tree Swapping, Next: How to Avoid Unnecessary Tree Swapping, Prev: Tree Swapping as a Possible Cause of Poor Application Performance, Up: How to Build Efficient ASIS Applications Queries That Can Cause Tree Swapping ==================================== In ASIS-for-GNAT, tree swapping can currently take place only when processing queries defined in: Asis.Elements Asis.Declarations Asis.Definitions Asis.Statements Asis.Clauses Asis.Expressions Asis.Text except the queries that return enumeration or boolean results. For any instantiation of Asis.Iterator.Traverse_Element, the traversal itself can cause at most one tree read to get the tree appropriate for processing the Element to be traversed, but procedures provided as actuals for Pre_Operation and Post_Operation may cause additional tree swappings.  File: asis_ug.info, Node: How to Avoid Unnecessary Tree Swapping, Next: Using gnatmake to Create Tree Files, Prev: Queries That Can Cause Tree Swapping, Up: How to Build Efficient ASIS Applications How to Avoid Unnecessary Tree Swapping ====================================== To speed up your application, try to avoid unnecessary tree swapping. The following advices may help you in this: 1. Try to minimize a set of tree files processed by your application. In particular, try to avoid having separate trees created for subunits. Minimizing of a set of tree files processed by the application also cuts down the time needed for opening a Context. Try to use gnatmake to create a suitable set of tree files covering an Ada program for processing by an ASIS application. 2. Choose the right way of Context definition for your application. For example, use "one tree" Context (-C1) for applications that are limited to processing single units (such as a pretty printer or gnatstub). By processing the tree file created for this unit, ASIS can get all the syntax and semantic information about this unit. Using "one tree" Context definition, an application has only one tree file to read during opening a Context, and no other tree file will be read during the application run. A "N-trees" Context is a natural extension of "one tree" Context for applications which know in advance what units shall be processed, but opening a Context becomes longer, and ASIS may switch among different tree files during an application run. Use "all trees" Context only for applications which are not targeted at processing a specific unit or a specific set of units, but are supposed to process all the available units, or in case when an application has to process a big system consisting of a large number of units. When using an application based on "all trees" context, use the approach for creating tree files described above to minimize a set of tree files to be processed. 3. In your application, try to avoid switching between processing units or sets of units with no dependencies among them - such a switching will certainly cause tree swapping. 4. If you are going to analyze some library unit having both spec and body, start from obtaining an Element from the body of this unit. This will set the tree created for the body as the tree accessed by ASIS, and this tree will be enough for processing both the spec and the body of this unit without tree swapping. 5. To see "tree swapping profile" of your application use -dt debug flag when initializing ASIS ( Asis.Implementation.Initialize ("-dt") ). The information you will get from the application run may give you some hints how to avoid tree swapping.  File: asis_ug.info, Node: Using gnatmake to Create Tree Files, Prev: How to Avoid Unnecessary Tree Swapping, Up: How to Build Efficient ASIS Applications Using `gnatmake' to Create Tree Files ===================================== To create a suitable set of tree files, you may use `gnatmake'. GNAT creates the ALI files for every successful compilation, whether or not the code has been generated. Therefore, it is possible to run `gnatmake' with -gnatc and -gnatt parameters, and this will create the set of tree files representing all the compilation units needed by a unit to which `gnatmake' is applied to be included in a partition. Below we will use `gnatmake' to create a set of tree files for a complete Ada program (partition). You may adapt this approach to an incomplete program or to a partition without a main subprogram, applying gnatmake to some of its components. Using `gnatmake' for creating tree files has another advantage - this will keep tree files consistent among themselves and with the sources. There are two different ways to use `gnatmake' to create a set of tree files. First, suppose you have object, ALI and tree files for your program in the same directory, and `main_subprogram.adb' contains the body of the main subprogram. If you run `gnatmake' as gnatmake -f -c ... main_subprogram.adb -cargs -gnatc -gnatt or simply as gnatmake -f -c -gnatc -gnatt ... main_subprogram.adb this will create the trees representing the full program for which main_subprogram is the main procedure. The trees will be created from scratch, that is, if some tree files already exist, they will be recreated. This is because gnatmake is called with -f option (which means "force recompilation"). Usng gnatmake without -f option for creating tree files is not reliable if your tree files are in the same directory with object files, because object and tree files "share" the same set of ALI files, and in case of object file existing and being consistent with the ALI and source files, the source will not be recompiled for creating a tree file if -f option was not set. A different approach is to keep the tree files and the associated ALI files in a separate directory, and to use this directory only for keeping the tree files and maintaining their consistency with source files (that is, object files and ALI files corresponding to them should be in another directory). In this case, by calling gnatmake as gnatmake -c ... main_subprogram.adb -cargs -gnatc -gnatt or simply as gnatmake -c -gnatc -gnatt ... main_subprogram.adb (that is, without forcing recompilation) you will still get the full and consistent set of tree files representing your programs, but in this case the existing tree files will be reused. See the next section for specific details related to Ada compilation units belonging to precompiled Ada libraries.  File: asis_ug.info, Node: Processing an Ada Library by an ASIS-Based Tool, Next: Compiling Binding and Linking Applications with ASIS-for-GNAT, Prev: How to Build Efficient ASIS Applications, Up: Top Processing an Ada Library by an ASIS-Based Tool *********************************************** In the cases when an Ada program to be processed by some ASIS-based tool makes use of some Ada library, it is necessary to be aware of the following features of using Ada libraries in case of GNAT: * an Ada library is a collection of precompiled Ada components. The sources of the Ada components belonging to the library are also presented as a part of a library, but if a user program uses some components from a library, these components are not recompiled when calling gnatmake (in a usual way) for this program (for example, you never recompile Ada.Text_IO when you call gnatmake for any program which uses Ada.Text_IO; * according to the GNAT source-based compilation model, specs of library components are processed when a user unit which uses these components is compiled, but bodies of library components are not compiled. As a result, if you call gnatmake to create a set of tree files covering a given program, and if this program uses something from some Ada library, then the set of tree files created by such a call will contain only specs, but not bodies for library components; * any GNAT installation contains the GNAT Run-Time Library (RTL) as a precompiled Ada library. In some cases, a GNAT installation may contain some other libraries (such as Win32Ada Binding in case of Windows95/NT GNAT porting); * in ASIS-for-GNAT, there is no reliable way to define whether or not a given Compilation Unit belongs to some precompiled Ada library other then GNAT RTL (some euristics may be added to Asis.Extensions). ASIS-for-GNAT classifies (by means of Asis.Compilation_Units.Unit_Origin query) a unit as A_Predefined_Unit, if it is from RTL and if it is mentioned in RM95 A(2) as an Ada 95 predefined unit, and a unit is classified as An_Implementation_Unit if is belongs to RTL, but is not mentioned in RM 95 A(2). Components of Ada libraries other then RTL are always classified as An_Application_Unit; * there is a possibility to recompile the components of the Ada libraries used by a given program. To do this, you have to call gnatmake for this program with '-a' gnatmake option. Therefore, if you create a set of tree files for you program by calling gnatmake with '-a' option, the resulting set of tree files will contain all the units needed by this program to make up a complete partition. Therefore, there are two possibilities for ASIS-based tools and their users in case if processing (or avoiding processing) of Ada libraries is important for the functionality of the tool: 1. If the tool does not want to process components of Ada libraries, then a set of tree files for this tool may be created by calling gnatmake without '-a' option (this is the usual way of using gnatmake). When the tool faces a Compilation_Which which represents a spec of some library unit, and for which Asis.Compilation_Units.Is_Body_Required gives True, but Asis.Compilation_Units. Corresponding_Body yields a result of A_Nonexistent_Body kind, then the tool may conclude that this library unit belongs to some precompiled Ada library; 2. If a tool wants to process all the Ada compilation units making up a program, then a set of tree files for this program should be created by calling gnatmake with '-a' option; 3. Asis.Compilation_units.Unit_Origin may be used to filter out RTL components.  File: asis_ug.info, Node: Compiling Binding and Linking Applications with ASIS-for-GNAT, Next: ASIS-for-GNAT Warnings, Prev: Processing an Ada Library by an ASIS-Based Tool, Up: Top Compiling, Binding and Linking Applications with ASIS-for-GNAT ************************************************************** If you have installed ASIS-for-GNAT as an Ada library and added the directory containing all source, ALI and library files of this library to the values of the ADA_INCLUDE_PATH and ADA_OBJECTS_PATH environment variables (which is a recommended way to install ASIS-for-GNAT), you do not need any ASIS-specific options for the GNAT compiler (that is, for gcc calls) and for gnatbind when working with your ASIS applications. However for gnatlink you have to provide an additional parameter "-lasis": gnatlink my_application -lasis When using `gnatmake', you also have to provide this linker parameter whenever a call to `gnatmake' invokes `gnatlink': gnatmake ... my_application -largs -lasis You do not need these linker parameters if a call to gnatmake is not creating the executable: gnatmake -c ... my_application If you have installed ASIS-for-GNAT without building an ASIS library, then you have to do the following when working your ASIS application code: * when compiling, you have to put catalogs with ASIS-for-GNAT implementation sources (asis-[version#]-src/asis and asis-[version#]-src/gnat) in the search path for the source files; you may do it either by -I gcc options or by adding these directories in the ADA_INCLUDE_PATH environment variable; * when binding, you have to put the directory where all the object and ALI files for the ASIS-for-GNAT components were created (asis-[version#]-src/obj, if you followed the manual installation procedure described in README/ASIS Installation Guide) in the search path for gnatbind, you can do it either by -aO gnatbind option or by adding this directory in the ADA_OBJECTS_PATH environment variable; If you have added directories with ASIS-for-GNAT source, object and ALI files to the values of the GNAT-specific environment variables, you do not have to provide any ASIS-specific parameter when using gnatmake for your ASIS application.  File: asis_ug.info, Node: ASIS-for-GNAT Warnings, Next: File Naming Conventions and Applications Name Space, Prev: Compiling Binding and Linking Applications with ASIS-for-GNAT, Up: Top ASIS-for-GNAT Warnings ********************** The ASIS definition specifies the situations when a certain ASIS-defined exception should be raised, and ASIS-for-GNAT follows these rules. ASIS-for-GNAT also generates warnings if it considers some situation arising during the ASIS query processing to be potentially wrong, and if the ASIS definition does not require to raise an exception in this case. Usually this is the case for actual or potential problems happening in an implementation-specific parts of the ASIS functionality, such as providing implementation-specific parameters to the queries Initialize, Finalizes and Associate or opening a Context. There are three warning modes in ASIS-for-GNAT: default warning messages are generated into stderr; suppress warning messages are suppressed; treat as error a warning is treated as an error by ASIS-for-GNAT: instead of sending a message to stderr, ASIS-for-GNAT raises Asis_Failed and converts the warning message into the ASIS Diagnosis string. ASIS Error Status depends on the cause of the warning. The ASIS-for-GNAT warning mode may be set when initializing the ASIS implementation. The "-ws" parameter of Asis.Implementation.Initialize query suppresses warnings, "-we" parameter of this query sets treating all the warnings as errors. When set, the warning mode remains the same for all Contexts processed until ASIS-for-GNAT has finalized.  File: asis_ug.info, Node: File Naming Conventions and Applications Name Space, Prev: ASIS-for-GNAT Warnings, Up: Top File Naming Conventions and Application's Name Space **************************************************** Any ASIS application being developed with ASIS-for-GNAT depends on the ASIS interface components and, transitively on other ASIS-for-GNAT implementation components. Therefore, the name space available for application's compilation unit names in the very beginning of the application development already contains some names, which cannot be used as the names of application's components. ASIS-for-GNAT includes the full specification of the ISO/IEC 15291:1999 ASIS Standard. The following children and grandchildren of the top Asis package are added in ASIS-for-GNAT * Asis.Extensions hierarchy (the source file names start from `asis-extensions' - defines some useful ASIS extensions, see ASIS Reference Manual for more details; * Asis.Set_Get (the source files `asis-set_get.ad[bs]' respectively) - contains the access and update routines for the implementation of the main ASIS abstractions defined in Asis; * Asis.Text.Set_Get (the source files `asis-text-set_get.ad[bs]' respectively - contains the access and update routines for the implementation of the ASIS abstractions defined in Asis.Text; All other ASIS-for-GNAT Ada implementation components belong to the hierarchy headed by the package named A4G (which comes from ASIS-for-GNAT) and have names starting from "A4G.". ASIS-for-GNAT also incorporates the following GNAT components as a part of the ASIS implementation: Alloc Atree Casing Csets Debug Einfo Elists Fname Gnatvsn Hostparm Krunch Lib Lib-List Lib-Sort Namet Nlists Opt Output Repinfo Scans Sinfo Sinput Snames Stand Stringt Table Tree_In Tree_Io Types Uintp Uname Urealp Widechar Therefore, in your ASIS application you can use for your Ada components any names except package names defined by ASIS as the names of the ASIS interface packages, Asis.Extensions, Asis.Set_Get, Asis.Text.Set_Get, and any name from the hierarchy headed by "A4G" and any name from the list of the GNAT component names given above. All Ada source files making up the ASIS implementation for GNAT (including the GNAT components being a part of ASIS-for-GNAT) follow the GNAT file name conventions without any name krunching.